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Preface 


This manual includes functional VMS Version 5.1 enhancements that 
support the new DECwindows environment. Components with new 
features include VAXTPU, RMS, CDA, and DCL. The following types 
of enhancements have been made: 


Enhancements that provide support for DECwindows graphic and 
windowing capabilities. 


Enhancements to support a new VMS file format. The new file format 
allows encoding of compound documents. Compound documents are 
files consisting of a number of integrated components such as text, 
graphics, and scanned images. 


The following four DCL commands and one DCL qualifier have been 
added: 


Intended Audience 


CONVERT/DOCUMENT command 
EXCHANGE/NETWORK command 
SET DISPLAY command 

SHOW DISPLAY command 

SET FILE/SEMANTICS qualifier 


This manual is intended for all system users of VMS and DECwindows. 
However, the VAXTPU section of this manual is for experienced VAXTPU 
programmers. 


Document Siructure 


This manual consists of the following chapters: 


Chapters 1—7 describe the VAXTPU and EVE new features. 
Chapter 8 describes the CDA new features. 
Chapter 9 describes the VMS RMS new features. 


Chapter 10 describes the new DCL command 
EXCHANGE/NETWORK. 


Chapter 11 describes the new DCL commands SET DISPLAY and 
SHOW DISPLAY. 
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Associated Documents 


For additional information about topics discussed in this document, see 
the following manuals: 


¢ VMS Compound Document Architecture Manual 

e VMS Version 5.1 Release Notes 

e¢ VMS DECwindows User’s Guide 

¢ VMS DECwindows Guide to Application Programming 
e XUI Style Guide 

e VAX Text Processing Utility Manual 


Conventions 


mouse 
MB1, MB2, MB3 


PBi, PB2, PB3, PB4 
SB1, SB2 
Cirl/x 


PF1 x 
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The following conventions are used in this manual: 
The term mouse is used to refer to any pointing device, such as a mouse, a puck, or a 
stylus. | 


MB1 indicates the left mouse button, MB2 indicates the middle mouse button, and 
MB3 indicates the right mouse button. (The buttons can be redefined by the user.) 


PB1, PB2, PB3, and PB4 indicate buttons on the puck. 
SB1 and SB2 indicate buttons on the stylus. 


A sequence such as Ctrl/x indicates that you must hold down the key labeled Ctrl while 
you press another key or a pointing device button. 


A sequence such as PF1 x indicates that you must first press and release the key 
labeled PF1, then press and release another key or a pointing device button. 


A key name is shown enclosed to indicate that you press a key on the keyboard. 
In examples, a horizontal ellipsis indicates one of the following possibilities: 


¢ Additional optional arguments in a statement have been omitted. 
¢ The preceding item or items can be repeated one or more times. 
¢ Additional parameters, values, or other information can be entered. 


A vertical ellipsis indicates the omission of items from a code example or command 
format; the items are omitted because they are not important to the topic being 
discussed. 


In format descriptions, parentheses indicate that, if you choose more than one option, 
you must enclose the choices in parentheses. 


In format descriptions, brackets indicate that whatever is enclosed is optional; you can 
select none, one, or all of the choices. Brackets enclosing a comma and horizontal 
ellipsis mean that you can repeat the preceding item one or more times, separating 
two or more items with commas. 


red ink 


boldface text 
italic text 


UPPERCASE TEXT 


UPPERCASE letters 
and special symbols 


lowercase letters 


user_ 
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Double brackets in examples show an optional portion of the format of a built-in 
procedure or lexical element. When double brackets enclose an item or series of 
items, you can select one of the items. Double brackets enclosing a comma and 
horizontal ellipsis mean that you can repeat the preceding item one or more times, 
separating two or more items with commas. For example: 


parameter [[,...]] 


In format descriptions, braces surround a required choice of options; you must choose 
one of the options listed. Braces enclose a mandatory portion of the format of a built-in 
procedure or lexical element. When braces enclose a stacked list of items, you must 
string } 


choose one of the items. For example: { 
range 


Red ink indicates information that you must enter from the keyboard or a screen object 
that you must choose or click on. For online versions, user input is shown in bold. 


Boldface text represents the introduction of a new term. 


Italic text represents information that can vary in system messages (for example, 
Internal error number). 


Uppercase letters indicate that you must enter a command (for example, enter 
OPEN/READ). Uppercase letters can also indicate the name of a routine, the name of 
a file, the name of a file protection code, or the abbreviation for a system privilege. 


Uppercase letters and special symbols in syntax descriptions and sample procedures 
indicate VAXTPU reserved words and predeclared identifiers, and other user input 
which must be typed exactly as shown. For example: 


PROCEDURE 
UNDERLINE 


String constants are shown in lowercase to emphasize that they are strings. However, 
they, too, must be typed exactly as shown. 


Lowercase letters in syntax descriptions and sample procedures represent elements 
you must replace according to the description in the text. For example, when a data 
type, such as buffer, is used in a syntax example, replace it with the variable name 
assigned to the data item when it was created. In the following assignment statement, 
my_buffer_variable is the variable name assigned to the buffer you are creating: 


my buffer variable := 
CREATE BUFFER (‘my buf name’, ‘my file name’) 


To specify a buffer as a parameter for a VAXTPU built-in procedure, use the variable 
for the buffer. For example, to erase the contents of the buffer created in the preceding 
statement, enter the following: 


ERASE (my _ buffer variable) 


The prefix user_ is used in many sample procedures as a part of the procedure name. 
DIGITAL suggests that you replace the prefix user with your initials. This (or another 
convention of your choice) helps to ensure that the variables and procedure names 
that you create do not conflict with either VAXTPU built-in procedure names, or the 
procedure names and variables of your editing interface. 
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Overview of the DECwindows VAX Text Processing 
Utility 


This chapter presents an overview of the VAX Text Processing Utility 
(VAXTPU) Version 2.2, released with VMS Version 5.1. 


This chapter discusses the following: 


¢ The relationship between this version of VAXTPU and other versions 
of VAXTPU 


e The DECwindows version of VAXTPU 


e The relationship between DECwindows VAXTPU and other 
DECwindows features (such as the XUI Toolkit or Xlib) 


¢ The relationship between DECwindows VAXTPU and the DECwindows 
User Interface Language (UIL) 


Note: The VAXTPU section of this manual is intended for experienced 
VAXTPU programmers who have read the VMS DECwindows Guide 
to Application Programming and who have access to the VAX Text 
Processing Utility Manual. 


1.1 Relationship to Previous Versions of VAXTPU 


This section of the VMS Version 5.1 New Features Manual documents 
VAXTPU Version 2.2, which is the version of VAXTPU released with VMS 
Version 5.1. If you need to submit a Software Problem Report (SPR) on 
the version of VAXTPU released with VMS Version 5.1, please state in the 
SPR that you are reporting a problem with VAXTPU Version 2.2. 


VAXTPU Version 2.2 includes a DECwindows version of VAXTPU and 

a non-DECwindows version of VAXTPU. You can use the DECwindows 
version of VAXTPU only on a workstation that supports DECwindows. For 
information about how to invoke the DECwindows version of VAXTPU, see 
Chapter 3. 


Both versions of VAXTPU released with VMS Version 5.1 include all 
the built-in procedures and features provided in the version of VAXTPU 
released with VMS Version 5.0, plus some new built-in procedures and 
other features. This manual documents only the features of VAXTPU 
that are new in the version of VAXTPU released with VMS 5.1. Use this 
manual as a supplement to the VAX Text Processing Utility Manual. 


Some new VAXTPU features are available in both the DECwindows 
and the non-DECwindows versions of VAXTPU. Other new VAXTPU 
features are available only in the DECwindows version of VAXTPU. All 
new features of VAXTPU are available in the DECwindows version. 
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1.1 Relationship to Previous Versions of VAXTPU 


The difference between the DECwindows version of VAXTPU 2.2 and the 
non-DECwindows version of VAXTPU 2.2 is that DECwindows VAXTPU 
includes the built-in procedures needed to implement a DECwindows text 
processing interface, while the non-DECwindows version does not include 
these built-ins. 


Note that the “windows” referred to in the product name DECwindows 
are not the same as VAXTPU windows, which have been supported in 
VAXTPU for several releases. For more information about the difference 
between DECwindows windows and VAXTPU windows, see Chapter 6. 


Any VAXTPU program or package written using the version of VAXTPU 
released with VMS Version 5.0 will still work under either version of 
VAXTPU released with VMS Version 5.1, even if the old program or 
package does not implement a DECwindows text processing interface. 


1.2 The DECwindows Version of VAXTPU 


The DECwindows version of the VAX Text Processing Utility (VAXTPU) is 
a programmable utility that includes the following tools: 


e A language (a set of statements and reserved words plus a set of 
syntax rules) 


e An interpreter 
¢ Acompiler 
¢ A callable interface 


e A default editing interface, the Extensible VAX Editor (EVE), written 
in the VAXTPU language 


¢ A set of built-in procedures that you can use to implement a 
DECwindows text processing interface 


DECwindows VAXTPU is designed as a tool to aid application and system 
programmers in developing text editors and other text-manipulating 
products. Using programs composed of VAXTPU statements, you can 
create products that have DECwindows interfaces. For more information 
about the DECwindows interfaces, see the XUI Style Guide. 


You can also use DECwindows VAXTPU to create text processing products 
with command-line interfaces (interfaces that you control by typing in 
commands). 


For general information about creating editors and other products using 
VAXTPU, see the VAX Text Processing Utility Manual. 


1.3 DECwindows VAXTPU and DECwindows Features 


The DECwindows environment has a number of toolkits and libraries 
containing routines for creating and manipulating DECwindows interfaces. 
For example, DECwindows routines allow you to create and manipulate 
clipboard entries, global selections, and widgets. For an overview of the 
DECwindows libraries and toolkits, see VMS DECwindows Guide to 
Application Programming. 
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1.3 DECwindows VAXTPU and DECwindows Features 


DECwindows VAXTPU contains a number of built-in procedures that call 
some of the routines in the various DECwindows libraries and toolkits. 


Using these DECwindows VAXTPU built-in procedures, you can create 
and manipulate various features of a DECwindows interface from within 
a VAXTPU program. For a list of the kinds of widgets you can create and 
manipulate using VAXTPU built-in procedures, see Chapter 7. In most 
cases, you use VAXTPU DECwindows built-in procedures without needing 
to know what DECwindows routine a given built-in procedure calls. 


You cannot directly call DECwindows routines (such as XUI Toolkit or Xlib 
Toolkit routines) from within a program written in the VAXTPU language. 
To use a DECwindows routine in a VAXTPU program, you can use one or 
more of the following techniques: 


¢ Use a VAXTPU built-in procedure that calls a DECwindows routine. 
Examples of such VAXTPU built-in procedures include the following: 


— CREATE_WIDGET 

— DELETE (WIDGET) 

— MANAGE_WIDGET 

— SET (DRM_HIERARCHY) 
— SET (WIDGET) 

— SET (WIDGET_CALLBACK) 
— UNMANAGE_WIDGET 


For more information about how to use the DECwindows built-ins in 
VAXTPU, see the individual built-in descriptions in Chapter 5. For 
more information about the types of widget resource values supported 
by VAXTPU, see Chapter 7. 


e Using a compiled language that follows the VMS calling standard, 
write a function calling the desired XUI Toolkit routine. You can then 
use the built-in procedure CALL_USER in your VAXTPU program to 
invoke the program written in the non-VAXTPU language. For more 
information about using the built-in procedure CALL_USER, see the 
VAX Text Processing Utility Manual. 


e Using a compiled language that follows the VMS calling standard, 
write a program calling the desired XUI Toolkit routine. You can then 
use the VAXTPU callable interface to invoke the program written in 
the non-VAXTPU language. For more information about using the 
VAXTPU callable interface, see the VMS Utility Routines Manual. 


The DECwindows version of VAXTPU 2.2 does not supply built-in 
procedures implementing all DECwindows routines. For example, there 
are no VAXTPU built-in procedures to handle pixmaps or floating-point 
numbers or to manipulate entities such as lines, curves, and fonts. 


However, the DECwindows version of VAXTPU 2.2 allows you to create a 
wide variety of widgets, to designate callback routines for those widgets, to 
fetch and set geometry- and text-related resources of the widgets, and to 
perform other functions related to creating a DECwindows text processing 
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interface. For example, the DECwindows EVE editor is a text processing 
interface created with DECwindows VAXTPU. 


You can use VAXTPU programs with DECwindows User Interface 
Language (UIL) files just as you would use programs in any other 
language with UIL files. For an example of a VAXTPU program and a 
UIL file designed to be used together, see the description of the CREATE_ 
WIDGET built-in in Chapter 5. For more information about using UIL 
files in conjunction with programs written in other languages, see VMS 
DECwindows Guide to Application Programming. 


Pa Invoking DECwindows VAXTPU with FileView 


In the DECwindows version of VAXTPU, you can invoke VAXTPU by using 
FileView, a menu-driven interface for choosing and using files. DIGITAL 
recommends that you specify only one file at a time when you invoke 
VAXTPU this way. For general information about using FileView, see the 
VMS DECwindows User’s Guide. 


To invoke DECwindows VAXTPU using FileView, take the following steps: 
1 Choose the Files menu from the FileView menu bar. 
2 From the Files menu, choose the Edit menu item. 


FileView displays the Edit dialog box with a field in which to specify 
the file to edit and a set of radio buttons with which to choose the 
editor. 


3 Optionally, supply the specification of a file to edit if FileView has not 
supplied one. 


Choose the EVE editor. 
Click on OK. 


FileView displays a dialog box allowing you to invoke VAXTPU with 
any command qualifiers except the /[NO]JREAD, /[NOJRECOVER, and 
/[NO]JJOURNAL qualifiers. The /[NO]JJOURNAL and /[NOJRECOVER 
qualifiers do not appear in the dialog box because the DECwindows 
version of VAXTPU does not support journaling. The /[NOJREAD 
qualifier does not appear because /[NOJREAD can interact with 
/[NOJWRITE in unproductive ways if specified incorrectly. You 

can accomplish any result you need using /[NO]WRITE. For more 
information about the use of these qualifiers, see the VAX Text 
Processing Utility Manual. 


Figure 2-1 shows the layout of the dialog box used to invoke VAXTPU. 
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Figure 2-1 Layout of the VAXTPU Dialog Box 
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3 Changes to Command Line Qualifiers and Data Types 


This chapter provides information on the following subjects: 
¢ Behavior of the /DISPLAY command qualifier in VAXTPU Version 2.2 
e New and modified data types in VAXTPU Version 2.2 


3.1 Behavior of the /DISPLAY Command Qualifier 


To choose the DECwindows or the non-DECwindows version of VAXTPU, 
use the command qualifier /DISPLAY on the DCL command line when you 
invoke VAXTPU. 


VAXTPU supplies two keywords that you can use for specifying the 
version you want. The syntax for the /DISPLAY qualifier is as follows: 


= CHARACTER_CELL 
| Suilasien [ = DECWINDOWS | 


/NODISPLAY 


The /DISPLAY command qualifier is optional. By default, VAXTPU uses 
the non-DECwindows version, regardless of whether you are running 
VAXTPU on a workstation or a terminal. 


If you specify /DISPLAY = CHARACTER_CELL, VAXTPU uses its 
character-cell screen manager, which implements the non-DECwindows 
version of VAXTPU by running in a DECterm (or VWS) terminal emulator 
or on a physical terminal. 


If you specify /DISPLAY = DECWINDOWS, and if the DECwindows 
environment is available, VAXTPU uses the DECwindows screen manager, 
which creates a DECwindows window in which to run VAXTPU. 


If you specify /DISPLAY = DECWINDOWS and the DECwindows 
environment is not available, VAXTPU uses its character-cell screen 
manager to implement the non-DECwindows version of VAXTPU. 


To override the default without using the /DISPLAY qualifier, define 
the logical name TPU$DISPLAY_MANAGER to be DECWINDOWS, as 
follows: 


$ DEFINE TPUSDISPLAY MANAGER DECWINDOWS 


For more information about the difference between a DECwindows window 
and a VAXT'PU window, see Chapter 6. 


For more information about the /[NO]JDISPLAY qualifier, see the VAX Text 
Processing Utility Manual. 
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3.2 New and Modified Data Types 


This section covers data types that are new or modified in VAXTPU 
Version 2.2. For more information about VAXTPU data types, see the VAX 
Text Processing Utility Manual. 


3.2.1 Widgets 


The DECwindows version of VAXTPU Version 2.2 provides the widget data 
type to support DECwindows widgets. The non-DECwindows version of 
VAXTPU Version 2.2 does not support this data type. 


A widget is a structure used as an interaction mechanism by which users 
give input to an application or receive messages from an application. For 
more information about what a widget is, see the VMS DECwindows 
Guide to Application Programming. 


You can use the equal operator (=) or the not-equal operator (<>) on 
widgets to determine whether they are equal (that is, whether they 
are the same widget instance), but you cannot use any other relational 
or arithmetic operators on them. For more information about the 
difference between a class of widgets and a widget instance, see the 
VMS DECwindows Guide to Application Programming. 


Once you have created a widget instance, VAXTPU does not delete the 
widget instance, even if there are no variables referencing it. To delete a 
widget, use the DELETE (widget_variable) built-in. 


The DECwindows version of VAXTPU provides the same support for 
DECwindows gadgets that it provides for widgets. A gadget is a structure 
similar to a widget, but is not associated with its own unique DECwindows 
window. Gadgets do not require as much memory to implement as widgets 
do. In most cases, you can use the same DECwindows VAXTPU built-ins 
on gadgets that you use on widgets. For more information about gadgets, 
see the VMS DECwindows Guide to Application Programming. 


3.2.2 String Data Types 


Both the DECwindows and non-DECwindows versions of VAXTPU 
Version 2.2 allow you to replicate and reduce character strings. 


To replicate a string, specify the string to be reproduced, then the 
multiplication operator (*), and then the number of times you want 

the string to be replicated. For example, the following VAXTPU statement 
inserts 10 underscores into the current buffer at the editing point: 


COPY “TEXT” (7 "°# 10) 


Note that the string to be replicated must be on the left-hand side of the 
operator. For example, the following VAXTPU statement produces an 
error: 


COPY TEXT (10-% #.") 
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To reduce a string, specify the string to be modified, then the subtraction 
operator (—), and then the substring to be removed. For example, the 
following table shows the effects of two string-reduction operations: 


VAXTPU Statement Result 


COPY_TEXT ("FILENAME.MEM" - "FILE") Inserts the string 
"NAME.MEM*" into the current 
buffer at the editing point. 

COPY_TEXT ("LISTINGS.LIS" - "LIS") Inserts the string "TINGS.LIS" 
into the current buffer at the 
editing point. 
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New and Modified Built-In Procedures Common to Both 
the DECwindows and Non-DECwindows Versions of 


VAXTPU 


This chapter describes the new and modified built-in procedures that 

are common to both the DECwindows and non-DECwindows versions of 
VAXTPU Version 2.2. For information about the new DECwindows-related 
built-ins in VAXTPU Version 2.2, see Chapter 5. For information about 
the VAXTPU built-ins released before VMS Version 5.1, see the VAX Text 
Processing Utility Manual. For an overview of recent VAXTPU release 
history and version numbering, see Chapter 1. 


Descriptions of VAXTPU Built-In Procedures Common to DECwindows 


and Non-DECwindows 


Using the new and modified built-ins described in this section, you can 
perform the following tasks: 


e Convert location specifications from one coordinate system to another 
e Dynamically alter a range 

e Fetch information on window boundaries and size 

e Move the editing point to a specified record 


¢ Control whether a buffer is marked as modified 


For more information about using VAXTPU built-ins, see the VAX Text 
Processing Utility Manual. 
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CONVERT 
CONVERT 
Given the coordinates of a point in one coordinate system, returns the 
corresponding coordinates for the point in the coordinate system you specify. 
FORMAT DECW_ROOT_WINDOW 
CONVERT (} SCREEN 
window 
CHARACTERS, 
COORDINATES, 
from_x_integer, from_y_integer, 
DECW_ROOT_WINDOW 
SCREEN 
window 
CHARACTERS, 
COORDINATES, 
to_x_integer, to_y_integer) 
PARAMETERS DECW ROOT WINDOW 
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Specifies the coordinate system to be that used by the root window of the 
screen on which VAXTPU is running. 


SCREEN 


Specifies the coordinate system to be that used by the DECwindows 
window associated with VAXTPU’s top-level widget. 


window 
Specifies the coordinate system to be that used by the VAXTPU window. 


CHARACTERS 
Specifies a system that measures screen distances in rows and columns, as 


a character-cell terminal does. In a character-based system, the cell in the 
top row and the leftmost column has the coordinates (1,1). 


COORDINATES 


Specifies a DECwindows coordinate system in which coordinate units 
correspond to pixels. The pixel in the upper left corner has the coordinates 
(0, 0). 


from_xX_integer 
from_y_integer 


Integer values representing a point in the original coordinate system and 
units. 
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CONVERT 


to_x_integer 

to y integer 

Variables of type integer representing a point in the specified coordinate 
system and units. Note that the previous contents of the parameters is 
deleted when VAXTPU places the resulting values in them. You must 
specify VAXTPU variables for the parameters to_x_integer and to_y_ 
integer. Passing a constant integer, string or keyword value, causes an 
error. (This requirement does not apply to the parameters from_x_integer 
and from_y_integer.) | 


DESCRIPTION _ The converted coordinates are returned using the to_x_integer and to_y_ 
integer parameters. Note that coordinate systems are distinguished both 
by units employed and where each places its origin. 

SIGNALED TPU$_ARGMISMATCH ERROR The data t f the indicated 

ay e data type of the indica 

ERRORS parameter is not supported by the 

built-in. 

TPU$_BADDELETE ERROR You are attempting to modify 
an integer, keyword, or string 
constant. 

TPU$_INVPARAM ERROR One of the parameters was 
specified with data of the wrong 
type. 

TPU$_TOOFEW ERROR - Too few arguments passed to the 
built-in. 

TPU$_TOOMANY ERROR Too many arguments passed to 
the built-in. 

TPU$_BADKEY WARNING ~ You specified an invalid keyword 
as a parameter. 

TPU$_WINDNOTVIS WARNING CONVERT cannot operate on an 
invisible window. 

EXAMPLE The following example converts a point’s location from the current 


window’s coordinate system (with the origin in the upper left-hand corner 
of the window) to the VAXTPU screen’s coordinate system (with the 
origin in the upper left-hand corner of the VAXTPU screen). For more 
information about the difference between a VAXTPU window and the 
VAXTPU screen, see Chapter 6. If the current window is not the top 
window, CONVERT changes the value of the y-coordinate to reflect the 
difference in the VAXTPU screen’s coordinate system. 


PROCEDURE user convert 


LOCAL source x, 
source y, 


dest_ x, 
dest_y; 
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CONVERT | 


source xX : 
source y : 
dest_x 
dest_y 


1; 
Ly 


oOo ll Il 


a 


CONVERT (CURRENT WINDOW, COORDINATES, source xX, source y, SCREEN, COORDINATES, 
dest_x, dest_y); 


ENDPROCEDURE; 


For another example of a procedure using the CONVERT built-in, see 
Example 7-1. 
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CREATE RANGE 


Continues to behave as it did in the version of VAXTPU released with VMS 
Version 5.0, except that the video_attribute parameter is now optional. 


For more information on the CREATE_RANGE built-in and more examples of 
its use, see the VAX Text Processing Utility Manual. 


FORMAT range := CREATE RANGE (start_mark, end_mark 
[, video_attribute ]}) 


PARAMETERS _ start_mark 


The starting mark for the range. 


end_mark 
The ending mark for the range. 


video_attribute 

A keyword designating the new video attribute for the range. The 
attribute can be NONE, REVERSE, UNDERLINE, BLINK, or BOLD. 
If you do not specify the parameter, the default is NONE. 


return value The range that has been created. 


DESCRIPTION The syntax of the CREATE_RANGE built-in has been changed to make 
CREATE_RANGE more consistent with MODIFY_RANGE. The video 
attribute of the CREATE_RANGE built-in is now optional. If not specified, 
the attribute defaults to NONE. 


SIGNALED TPU$_NOTSAMEBUF WARNING First and d kK | 
a irst and second markers are in 
ERRORS different buffers. 
TPU$_TOOFEW ERROR CREATE_RANGE requires three 
parameters. 
TPU$_TOOMANY ERROR CREATE_RANGE accepts no 
more than three parameters. 
TPU$_NEEDTOASSIGN ERROR CREATE_RANGE must appear 


on the right-hand side of an 
assignment statement. 


TPU$_INVPARAM ERROR One of your arguments to 
CREATE_RANGE is of the wrong 
type. 

TPU$_BADKEY WARNING _ You specified an illegal keyword. 
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EXAMPLE The following statement creates a range with no video attributes: 


the_range := CREATE RANGE (first_marker, last_marker) ; 
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GET_ INFO (COMMAND LINE, "character") 


Fetches information about the character position specified when VAXTPU was 
invoked with the EDIT/TPU command. 


For more information about the GET_INFO built-in, see the VAX Text 
Processing Utility Manual. 


FORMAT 


integer := GET_INFO (COMMAND_LINE, "character") 


PARAMETERS 


COMMAND _LINE 
A keyword directing VAXTPU to return information about what qualifiers 
and values were specified when VAXTPU was invoked. 


"Character" 
A string indicating that the built-in is to return the column number of the 
character position specified by the /START_POSITION command qualifier. 


DESCRIPTION 


Returns the column number of the character position specified by the 
/START_POSITION command qualifier. This built-in is useful in a 
procedure to determine where VAXTPU should place the cursor at startup 
time. The default is 1 if the /START_POSITION qualifier is not specified. 


This built-in is a synonym for GET_INFO (COMMAND LINE, "start_ 
character"). For more information about the /START_POSITION qualifier, 
see the VAX Text Processing Utility Manual. | 
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GET_INFO (COMMAND LINE, "line") 


Fetches information about the record number specified when VAXTPU was 
invoked with the EDIT/TPU command. 


For more information about the GET_INFO built-in, see the VAX Text 
Processing Utility Manual. 


FORMAT integer :=GET_INFO (COMMAND_LINE, "line") 


PARAMETERS COMMAND_LINE 


A keyword directing VAXTPU to return information about what qualifiers 
and values were specified when VAXTPU was invoked. 


v9 ] i n e v7 
A string indicating that the built-in is to return the record number of the 
line specified by the /START_POSITION command qualifier. 


DESCRIPTION _ Returns the record number of the line specified by the /START_POSITION 
command qualifier. This built-in is useful in a procedure to determine 
where VAXTPU should place the cursor at startup time. The default is 1 if 
the /START_POSITION qualifier is not specified. 


This built-in is a synonym for GET_INFO (COMMAND_LINE, "start_ 
record"). For more information about the /START_POSITION qualifier, 
see the VAX Text Processing Utility Manual. 
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GET_INFO (integer_variable, name") 


Fetches information about the specified integer or keyword variable. 


For more information about the GET_INFO built-in, see the VAX Text 
Processing Utility Manual. 


ac iaciaia string := GET_INFO (| keyword, \ name") 
integer, 


PARAMETERS keyword 
A VAXTPU keyword whose string equivalent you want. Note that in 
VAXTPU, key names are of type KEYWORD. Therefore, you can use this 


parameter to specify a key name whose string equivalent you want. 


integer 

The integer equivalent of a VAXTPU keyword whose string equivalent 
you want. When coding in VAXTPU, do not use an ordinal value obtained 
from this GET_INFO call as a substitute for the corresponding keyword. 
DIGITAL does not guarantee that the existing equivalences between 
integers and keywords will always remain the same. 


“name” 
A string requesting GET_INFO to return the string equivalent of the 
specified integer or keyword. 


return value 
string The string representation of the specified keyword or integer equivalent 
of a keyword. 


Returns the string representation of a keyword or the integer equivalent of 
a keyword. The built-in performs all the functions that it performed in the 
version of VAXTPU released with VMS Version 5.0. In this version, the 
built-in has been enhanced so that if a key name is created using several 
key modifier keywords, the built-in returns the string representation of 
all the keywords used to create the key name. For more information on 
creating key names, see the description of the KEY_NAME built-in. 


DESCRIPTION 


For an explanation of the VAXTPU code in these examples, see the 
paragraph following each numbered code example. 


EXAMPLES __ 


4-9 


VAXTPU Built-Ins for DECwindows and Non-DECwindows Versions 
GET_INFO (integer_variable, "name") 


fl new_key := KEY_NAME (KP4, SHIFT MODIFIED, CTRL_MODIFIED) ; 
—_ 
: 
IF GET INFO (new_key, "key modifiers") 
THEN | 
the name := GET INFO (new_key, "name") 
ENDIF; 
MESSAGE (STR (the _name) ); 


The first statement in this code fragment creates a VAXTPU key name 
for the key sequence produced by pressing the Ctrl key, the Shift 

key, and the 4 key on the keypad, all at once. The new key name is 
assigned to the variable key_name. The IF clause of the statement 
shows how to test whether a key name was created using one or more 
key modifier keywords. (Note, however, that this statement would 
not detect whether a key name was created using the keyword Shift_ 
key. The built-in GET_INFO (key_name, "key_modifiers") returns 

0 even if the key name was created using SHIFT_KEY.) The THEN 
clause shows how to fetch the key modifier keyword or keywords 
used to create a key name. The final statement displays the string 
KEY_NAME (KP4, SHIFT_MODIFIED, ALT_MODIFIED) in the message 
buffer. 


equiv_string := GET INFO (14, "name"); 


This statement assigns the string object to the variable equiv_string. The 
value 14 is the integer equivalent of the keyword OBJECT. 
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GET_INFO (marker_variable, "record number") 


Fetches information about the specified marker. 


For more information about the GET_INFO built-in, see the VAX Text 
Processing Utility Manual. 


FORMAT integer := GET_INFO (marker_variable, 
"record_number") 


PARAMETERS /marker_variable 


The marker whose location you want the built-in to return. 


“record_number"” 
A string requesting GET_INFO to return the number associated with the 
record containing the specified marker. 


return value The number associated with the record containing the specified marker. 


DESCRIPTION This built-in returns the number associated with the record containing the 
specified marker. 


A record number indicates the location of a record in a buffer. Record 
numbers are dynamic; as you add or delete records, VAXTPU changes 

the number associated with a particular record, as appropriate. VAXTPU 
counts each record in a buffer, regardless of whether the line is visible in a 
window, or whether the record contains text. 


EXAMPLE The following statements establish a marker at the editing point, then 
fetch the number associated with the record where the marker is located: 

here := MARK (FREE CURSOR) ; 

wheres here := GET INFO (here, "record number"); 


4-11 


VAXTPU Built-Ins for DECwindows and Non-DECwindows Versions 
GET_INFO (mouse_event_keyword, "mouse_button") 


GET_INFO (mouse_event_keyword, "mouse_button") 


Fetches information about a mouse event. 


For more information about the GET_INFO built-in, see the VAX Text 
Processing Utility Manual. 


integer := GET INFO (mouse_event_keyword, 
"“mouse_bution") 


FORMAT 


PARAMETERS 


mouse_event_keyword 

A keyword representing a single click, multiple click, upstroke, 
downstroke, or drag of a mouse button. For a list of the valid keywords, 
see Table 4-1. 


“mouse_button" 


A string requesting GET_INFO to return the number of the specified 
mouse button. 


return value The number of the mouse button specified with the mouse_event_keyword 


parameter. 


DESCRIPTION _ Table 4-1 lists the valid keywords for this built-in. 
Table 4—1 VAXTPU Keywords Representing Mouse Events 
MiUP M2UP M3UP M4UP M5UP 
M1DOWN M2DOWN M3DOWN M4DOWN M5DOWN 
MiDRAG M2DRAG M3DRAG M4DRAG M5DRAG 
MiCLICK M2CLICK M3CLICK M4CLICK M5CLICK 
MiCLICK2 M2CLICK2 M3CLICK2 M4CLICK2 M5CLICK2 
MiCLICK3 M2CLICK3 M3CLICK3 M4CLICK3 M5CLICK3 
MiCLICK4 M2CLICK4 M3CLICK4 M4CLICK4 M5CLICK4 
MiCLICKS5 M2CLICK5 M3CLICK5 M4CLICK5 M5CLICK5 

EXAMPLES For an explanation of the VAXTPU code in these examples, see the 
paragraph following each numbered code example. 

x := GET INFO (M3CLICK2, "mouse button"); 
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the key := READ KEY; 
IF GET INFO (the key, "mouse button") = 3 
THEN 


MESSAGE ("MB3 has no effect in this context."); 


These statements test whether you have pressed MB3 and, if so, displays 
a message in the message window. 
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GET INFO (mouse _event_keyword, "window" ) 


Fetches the window in which the down stroke occurred that started the current 
drag operation. 


FORMAT a his GET_INFO (mouse_event_keyword, 
| window 


"window" 


PARAMETERS mouse_event_keyword 
A keyword representing the down stroke of one of the mouse buttons. The 
valid keywords for this parameter are M1DOWN, M2DOWN, M38DOWN, 
M4DOWN, and M5DOWN. 


"window" 
A string requesting GET_INFO to return the window in which the down 
stroke occurred that started the current drag operation. 


return value 
integer The value 0, which is returned if no drag operation is in progress for the 
specified mouse button when the built-in is executed. 


window The window in which the down click occurred that started the current 
drag operation. 


EXAMPLE The following procedure, when bound to M1DRAG, responds to a drag 
event by checking whether you have dragged the mouse across window 
bounds. If you have done so, the procedure displays a message. If not, the 
procedure creates a select range. 


PROCEDURE sample ml drag 


LOCAL the _ window, 
new window, 


column, 

row, 

temp; 
the window := GET INFO (M1DOWN, "window") ; 
IF the window = 0 
THEN 

RETURN (FALSE) 

ENDIF; 


LOCATE MOUSE (new_window, column, row); 
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IF the window <> new window 


THEN 
MESSAGE ("Invalid drag of pointer across window boundaries."); 


ENDIF; 
ENDPROCEDURE; 
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_ GET_INFO (SCREEN, "decwindows") 


GET_INFO (SCREEN, "decwindows") © 


Indicates whether VAXTPU is using its DECwindows screen updater. 


For more information about the GET_INFO built-in, see the VAX Text 
Processing Utility Manual. 


FORMAT integer := GET_INFO (SCREEN, "decwindows") 


PARAMETERS SCREEN 
A keyword indicating that GET_INFO is to fetch information about the 
VAXTPU screen. 


"decwindows"” 
A string requesting GET_INFO to indicate whether VAXTPU is using its 
DECwindows screen updater. 


return value Returns 1 if your system is running the DECwindows version of VAXTPU, 
otherwise 0. 
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GET_INFO (SCREEN, "line editing") 


On a character-cell terminal, indicates whether the line editing terminal 
attribute is turned on. 


For more information about the GET_INFO built-in, see the VAX Text 
Processing Utility Manual. 


FORMAT 


integer :=GET_INFO (SCHEEN, "line_editing") 


PARAMETERS 


return value 


SCREEN 
A keyword indicating that GET_INFO is to fetch information about the 
VAXTPU screen. 


"line_editing” 
A string requesting GET_INFO to indicate whether the line editing 
terminal attribute is turned on. 


On a character-cell terminal, returns 1 if the line editing terminal 
attribute is turned on, otherwise returns 0. In DECwindows VAXTPU, 
this built-in always returns 0. 
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GET_INFO (SCREEN, “original_length") 


Returns the number of lines the screen had when VAXTPU was started. 


For more information about the GET_INFO built-in, see the VAX Text 
Processing Utility Manual. 


FORMAT integer := GET_INFO (SCREEN, "original_length") 


PARAMETERS SCREEN ; | 
te A keyword indicating that GET_INFO is to fetch information about the 
VAXTPU screen. 


“original_length" 
A string indicating that GET_INFO is to fetch the number of lines the 
screen had when VAXTPU was started. 


return value The number of lines the screen had when VAXTPU was started. 
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GET_INFO (SYSTEM, "“timer") 


Indicates whether the built-in SET (TIMER) has been enabled. 


For more information about the SET (TIMER) built-in and the GET_INFO 
built-in, see the VAX Text Processing Utility Manual. 


FORMAT integer :=GET_INFO (SYSTEM, "timer") 


PARAMETERS SYSTEM 
A keyword indicating that GET_INFO is to fetch information about global 
settings in VAXTPU. 


"timer" 
A string indicating that GET_INFO is to indicate whether the SET 
(TIMER) built-in is enabled. 


return value The value 1 if the SET (TIMER) built-in is enabled, otherwise 0. 
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GET_INFO (window variable, "bottom") 


PARAMET 
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FORMAT 


ER 


window_variable 


Fetches the number of the last row or last visible row of the specified window, 
or the specified window’s text area. 


For more information about the GET_INFO built-in, see the VAX Text 
Processing Utility Manual. 


=GET INFO (window_variable, "bottom" 
, WINDOW 
, TEXT ) 
, VISIBLE_WINDOW 
, VISIBLE_TEXT 


integer : 


The window for which you want the specified row. 


“bottom” 
A string requesting GET_INFO to fetch the number of the last row or last 
visible row of the specified window or the specified window’s text area. 


TEXT 


A keyword directing the built-in to return the last window row on 
which text can be displayed. By specifying TEXT instead of VISIBLE_ 
TEXT, you obtain the window’s last text row even if that row is invisible 
because the window is occluded. If the window is not occluded, the value 
returned is the same as the value returned with VISIBLE_TEXT. GET_ 
INFO (window, "bottom", TEXT) is a synonym for GET_INFO (window, 
"original bottom"). 


VISIBLE_TEXT 


A keyword directing the built-in to return the number of the last visible 
window row on which text can be displayed. The call GET_INFO (window, 
"bottom", VISIBLE_TEXT) is a synonym for GET_INFO (window, "visible_ 
bottom"). When VAXTPU determines a window’s last visible text row for 
either of these built-ins, VAXTPU does not consider the status line or the 
bottom scroll bar to be a text row. 


VISIBLE_WINDOW 


A keyword directing the built-in to return the number of the last visible 
row in the window. There is no synonym for this call. 


WINDOW 


A keyword directing the built-in to return the number of the last row in 
the window. By specifying WINDOW instead of TEXT, you obtain the 
window’s last row, even if the last row cannot contain text because it 
contains a scroll bar or status line. By specifying WINDOW instead of 
VISIBLE_WINDOW, you obtain the window’s last row even if that row is 
invisible because the window is occluded. If the window is not occluded, 
the value returned is the same as the value returned with VISIBLE_ 
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WINDOW. GET_INFO (window, "bottom", WINDOW) is a synonym for 
GET_INFO ("original_bottom"). 


return value 
integer The number of the last row or last visible row. 


DESCRIPTION _ The window row whose number is returned depends on the keyword you 
specify. If you do not specify a keyword, the default is TEXT. 


EXAMPLE The following statement returns the last line of the window "bottom_ 
window." The value returned is the line containing the status line or scroll 
bar, whichever comes last, if the window has a status line or scroll bar. 


last_line := GET INFO (bottom window, "bottom", WINDOW) ; 


For another example of code using GET_INFO (window_variable, 
"bottom", WINDOW ) see Example 7—5. 
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GET_INFO (window_variable, "key_map_list") 


Fetches the string that is the name of the key map list associated with the 
window you specify. 


For more information about the GET_INFO built-in, see the VAX Text 
Processing Utility Manual. 


FORMAT string := GET_INFO (window_variable, 
"key_map_list") 


PARAMETERS '~ window_variable 


The window for which you want the associated key map list. 


"key_map_list" 
A string directing GET_INFO to fetch the key map list for the specified 


window. 
return value 

string The name of the key map list associated with the specified window. 
EXAMPLE The following statement returns the key map list associated with the 


current window: 
current_list := GET_INFO (CURRENT_WINDOW, "key map list"); 


For an example of code using GET_INFO (window_variable, "key_map_ 
list", WINDOW) see Example 7-6. 
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GET_INFO (window_variable, “left") 


Fetches the number of the leftmost column or leftmost visible column of the 
specified window, or the specified window’s text area. 


For more information about the GET_INFO built-in, see the VAX Text 
Processing Utility Manual. 


FORMAT integer := GET INFO (window_variable, "left" 
, WINDOW 
, TEXT ) 
, VISIBLE_ WINDOW 
, VISIBLE_ TEXT 
PARAMETERS’ window variable 


The window for which you want the leftmost column. 


"left" 

A string requesting GET_INFO to fetch the number of the leftmost column 
or leftmost visible column of the specified window or the specified window’s 
text area. 


TEXT 

A keyword directing the built-in to return the first window column in 
which text can be displayed. By specifying TEXT instead of VISIBLE_ 
TEXT, you obtain the window's first text column, even if that column is 
invisible because the window is occluded. If the window is not occluded, 
the value returned is the same as the value returned with VISIBLE_TEXT. 


In Version 2.2, the value returned with TEXT is also the same as the value 
returned with WINDOW. 


VISIBLE_TEXT 


A keyword directing the built-in to return the number of the first visible 
window column in which text can be displayed. 


VISIBLE_WINDOW 


A keyword directing the built-in to return the number of the first visible 
column in the window. 


WINDOW 

A keyword directing the built-in to return the number of the first column 
in the window. By specifying WINDOW instead of VISIBLE_WINDOW, 
you obtain the window’s first column even if that column is invisible 
because the window is occluded. If the window is not occluded, the value 
returned is the same as the value returned with VISIBLE_WINDOW. 
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return value 3 
Integer The number of the leftmost column or leftmost visible column. 


DESCRIPTION The column whose number is returned depends on the keyword you 
specify. If you do not specify a keyword, the default is TEXT. 


EXAMPLE The following statement returns the leftmost column where text can be 
displayed in the current window. Note that changing the left margin 
setting has no effect on the value returned. 


first_column := GET_INFO (CURRENT WINDOW, "left", TEXT); 
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GET_INFO (window variable, length") 


Fetches the number of rows or visible rows in the specified window or the 
specified window’s text area. 


For more information about the GET_INFO built-in, see the VAX Text 
Processing Utility Manual. 


FORMAT 


PARAMETERS 


integer := GET_INFO (window_variable, "length" 
, WINDOW 
, TEXT ) 
, VSIBLE_WINDOW 
, VISIBLE_TEXT 


window _variable 
The window for which you want the specified number of rows. 
"length" 


A string requesting GET_INFO to fetch the number of rows or visible rows 
in the specified window or the specified window’s text area. 


TEXT 

A keyword directing the built-in to return the number of window rows on 
which text can be displayed. By specifying TEXT instead of VISIBLE_ 
TEXT, you obtain the total number of window text rows even if some 

of them are invisible because the window is occluded. If the window is 
not occluded, the value returned is the same as the value returned with 
VISIBLE_TEXT. 


VISIBLE_TEXT 


A keyword directing the built-in to return the number of visible window 
rows on which text can be displayed. There is no synonym for this call. 


VISIBLE_WINDOW 

A keyword directing the built-in to return the number of visible rows 

in the window. GET_INFO (window, "length", VISIBLE_WINDOW) is 

a synonym for GET_INFO (window, "visible_length"). When VAXTPU 
calculates the visible text rows for either of these calls, VAXTPU does not 
consider the status line or the horizontal scroll bar to be a text row. 


WINDOW 

A keyword directing the built-in to return the number of rows in the 
window. By specifying WINDOW instead of TEXT, you obtain the total 
number of window rows even if the last rows cannot contain text because 
they contain a scroll bar or status line. By specifying WINDOW instead 
of VISIBLE_WINDOW, you obtain the total number of window rows even 
if some rows are invisible because the window is occluded. If the window 
is not occluded, the value returned is the same as the value returned 
with VISIBLE_WINDOW. GET_INFO (window, "length", WINDOW) is a 
synonym for the call GET_INFO (window, "original_length"). 
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return value | 
integer The number of rows or the number of visible rows. 


DESCRIPTION The number of rows returned depends on the keyword you specify. If you 
do not specify a keyword, the default is TEXT. 


EXAMPLE The following statement adds the length of the window (the value in 
the_window) to the value in the_length. Note that the length of the window 
includes the length added by the scroll bar and status line, if the window 
has them. 


the length := the length + GET _ INFO (the window, "length", WINDOW) ; 


For another example of code using GET_INFO (window_variable, "length", 
WINDOW) see Example 7-5. 


VAXTPU Built-Ins for DECwindows and Non-DECwindows Versions 
GET INFO (window_variable, "right") 


GET_INFO (window_variable, “right") 


Fetches the number of the last column or last visible column of the specified 
window or the specified window's text area. 


For more information about the GET_INFO built-in, see the VAX Text 
Processing Utility Manual. 


FORMAT integer :=GET_ INFO (window_variable, "right" 
, WINDOW 
, TEXT ) 
, VISIBLE_WINDOW 
, VISIBLE_TEXT 


PARAMETERS' window variable 


The window for which you want the specified row. 


"right" 

A string requesting GET_INFO to fetch the number of the last column or 
last visible column of the specified window or the specified window’s text 
area. 


TEXT 

A keyword directing the built-in to return the last window column in 
which text can be displayed. By specifying TEXT instead of VISIBLE_ 
TEXT, you obtain the window’s last text column even if that column is 
invisible because the window is occluded. If the window is not occluded, 
the value returned is the same as the value returned with VISIBLE_TEXT. 


VISIBLE_TEXT 


A keyword directing the built-in to return the number of the last visible 
window column in which text can be displayed. 


VISIBLE_WINDOW 


A keyword directing the built-in to return the number of the last visible 
row in the window. 


WINDOW 

A keyword directing the built-in to return the number of the last column 
in the window. By specifying WINDOW instead of TEXT, you obtain the 
window’s last column even if the last column cannot contain text because 
it contains a scroll bar. 


return value 
integer The number of the last column or last visible column. 
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DESCRIPTION _ The window column whose number is returned depends on the keyword 
you specify. If you do not specify a keyword, the default is TEXT. 


EXAMPLE The following statement returns the number of the rightmost column in 
the current window. Note that the column whose number is returned can 
be occupied by a vertical scroll bar if one is present. Note, too, that the 
returned value changes if you widen the window, but not if you move the 
window without widening it. 


last_column := GET_INFO (CURRENT WINDOW, "right", WINDOW) ; 
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GET_INFO (window_variable, "top") 


Fetches the number of the first row or first visible row of the specified window 
or the specified window's text area. 


For more information about the GET_INFO built-in, see the VAX Text 
Processing Utility Manual. 


FORMAT integer := GET INFO (window_variable, "top" 
, WINDOW 
, TEXT ) 
, VISIBLE_WINDOW 
, VISIBLE_TEXT 
PARAMETERS'- window _svariable 


The window for which you want the specified row. 


9 ve 

top 
A string requesting GET_INFO to fetch the number of the first row or first 
visible row of the specified window or the specified window’s text area. 


TEXT 

A keyword directing the built-in to return the first window row on which 
text can be displayed. By specifying TEXT instead of VISIBLE_TEXT, 
you obtain the window’s first text row even if that row is invisible because 
the window is occluded. If the window is not occluded, the value returned 
is the same as the value returned with VISIBLE_TEXT. In Version 2.2, 
the value returned by TEXT is also the same as the value returned by 
WINDOW. GET_INFO (window_variable, "top", TEXT) is a synonym for 
GET_INFO (window_variable, "original_top"). 


VISIBLE TEXT 


A keyword directing the built-in to return the number of the first visible 
window row on which text can be displayed. GET_INFO (window_variable, 
"top", VISIBLE_TEXT) is a synonym for GET_INFO (window_variable, 
"visible top"). 


VISIBLE_WINDOW 


A keyword directing the built-in to return the number of the first visible 
row in the window. 


WINDOW 

A keyword directing the built-in to return the number of the first row 

in the window. By specifying WINDOW instead of VISIBLE_WINDOW, 
you obtain the window’s first row even if that row is invisible because the 
window is occluded. If the window is not occluded, the value returned is 
the same as the value returned with VISIBLE_WINDOW. 

GET_INFO (window_variable, "top", WINDOW) is a synonym for 
GET_INFO (“original_top"). 
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return value 
integer The number of the first row or first visible row. 


DESCRIPTION The window row whose number is returned depends on the keyword you 
specify. If you do not specify a keyword, the default is TEXT. 


EXAMPLE The following statement returns the number of the first row in the current 
window. Note that the row number returned is relative to the top of the 
VAXTPU screen. Thus, if the current window is not the top window on the 
VAXTPU screen, the row number returned is not 1. 


first_row := GET _INFO (CURRENT WINDOW, "top", WINDOW) ; 


For another example of code using GET_INFO (window_variable, "top", 
WINDOW) see Example 7—5. 
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GET INFO (window variable, "width") 


Fetches the number of columns or the number of visible columns in the 
specified window or the specified window’s text area. 


For more information about the GET_INFO built-in, see the VAX Text 
Processing Utility Manual. 


FORMAT integer := GET_INFO (window_variable, "width" 
, WINDOW 
, TEXT ) 
, VISIBLE_WINDOW 
, VISIBLE_TEXT 


PARAMETERS'7- window variable 


The window for which you want the specified row. 


"width" 
A string requesting GET_INFO to fetch the number of columns or visible 
columns in the specified window or the specified window’s text area. 


TEXT 

A keyword directing the built-in to return the number of window columns 
in which text can be displayed. By specifying TEXT instead of VISIBLE_ | 
TEXT, you obtain the total number of window text columns even if some 
of them are invisible because the window is occluded. If the window 

is not occluded, the value returned is the same as the value returned 
with VISIBLE_TEXT. GET_INFO (window_variable, "width", TEXT) is a 
synonym for GET_INFO (window_variable, "width"). 


VISIBLE TEXT 


A keyword directing the built-in to return the number of visible window 
columns on which text can be displayed. There is no synonym for this call. 


VISIBLE_WINDOW 


A keyword directing the built-in to return the number of visible window 
columns in which text can be displayed. 


WINDOW 

A keyword directing the built-in to return the number of columns in 
the window. By specifying WINDOW instead of TEXT, you obtain the 
total number of window columns even if the last column cannot contain 
text because it contains a scroll bar. By specifying WINDOW instead 
of VISIBLE_WINDOW, you obtain the total number of window columns 
even if some columns are invisible because the window is occluded. If 


the window is not occluded, the value returned is the same as the value 
returned with VISIBLE_WINDOW. 
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return value 
integer The number of columns or the number of visible columns. 


DESCRIPTION The number of columns returned depends on the keyword you specify. If 
you do not specify a keyword, the default is TEXT. 


EXAMPLE The following statement returns the number of columns in the current 
window: 
the_width := GET_INFO (CURRENT WINDOW, "width", WINDOW) ; 


For an example of code using GET_INFO (window_variable, "width", 
WINDOW) see Example 7-6. 
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INT 


Accepts an integer as a parameter without generating an error. 


The INT built-in is supported in previous versions of VAXTPU. INT continues 
to perform all the functions it performed in previous versions; the addition 

of the data tyoe INTEGER as a valid data type for the parameter is new in 
DECwindows VAXTPU. 


For more information about the INT built-in, see the VAX Text Processing 
Utility Manual. 


FORMAT integer2 :=INT  (integer7) 


PARAMETERS = integer? 
Any integer value. INT accepts a parameter of type INTEGER so you need 
not check the type of the parameter you supply to the built-in. 


return value The integer equivalent of the parameter you specify. 
SIGNALED TPU$_NEEDTOASSIGN ERROR INT ret lue that tb 
returns a value that must be 
ERRORS = used. 
TPU$_TOOFEW ERROR INT requires one parameter. 
TPU$_TOOMANY ERROR INT accepts only one parameter. 
TPU$_ARGMISMATCH ERROR The parameter to INT was not a 
keyword or string. 
TPU$_INVNUMSTR WARNING _ The string you passed to INT was 
not a number. 
TPU$_NULLSTRING WARNING You passed a string of length 0 to 
INT. 
EXAMPLE The following statement assigns the integer 9 to the variable the_int: 
the ant. SENT: 19) 
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LOCATE MOUSE 


Returns the current position of the mouse if VAXTPU finds the mouse in a 
VAXTPU window. 


FORMAT 


[integer := ]] LOCATE MOUSE [| (window, x_integer, 
| y_integer) ] 


PARAMETERS 


return value 


window 

The window in which the pointer cursor is located. If the pointer cursor 
was not in a VAXTPU window at the time of the most recent keyboard or 
mouse event, this parameter is assigned the type UNSPECIFIED. 


x_integer 
The number of the window column where the pointer cursor is located. 
If the pointer cursor was not in a VAXTPU window at the time of the 


most recent keyboard or mouse event, this parameter is assigned the type 
UNSPECIFIED. 


y_in teger 

The number of the window row where the pointer cursor is located. If the 
pointer cursor was located on a window’s status line at the time of the 
most recent keyboard or mouse event, this parameter is assigned the value 
0. If the pointer cursor was not in a VAXTPU window at the time of the 


most recent keyboard or mouse event, this parameter is assigned the type 
UNSPECIFIED. 


integer The value 1 if VAXTPU finds a window position, otherwise 0. 


DESCRIPTION 


In the DECwindows version of VAXTPU, you can use the built-in 
LOCATE_MOUSE anytime after the first keyboard or mouse-button 
event. The built-in returns the location occupied by the pointer cursor at 
the time of the most recent keyboard or mouse button event. 


If there is no mouse information available (because no mouse button has 
been pressed or if the mouse has been disabled using SET (MOUSE)), 
LOCATE_MOUSE signals the status TPU$_MOUSEINV. 


SIGNALED 
ERRORS 
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TPU$_TOOFEW ERROR LOCATE_MOUSE requires three 
parameters. 


TPU$_TOOMANY ERROR LOCATE_MOUSE accepts at most 
three parameters. 
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TPU$_BADDELETE ERROR You have specified a constant as 
one or more of the parameters. 
TPU$_MOUSEINV WARNING No mouse button has been 
pressed or the mouse has been 
disabled. 
EXAMPLE The following statement returns an integer in the variable status 


indicating whether the pointer cursor was found in a window, the window 
in the parameter new_window where the mouse was found, an integer 

in the parameter x_value specifying the pointer cursor’s location in the 
horizontal dimension, and an integer in the parameter y_value specifying 
the pointer cursor’s location in the vertical dimension. 


status := LOCATE MOUSE (new_window, x_ value, y value); 


To see the LOCATE_MOUSE built-in used in a procedure, see 
Example 7-1 and Example 7-9. 
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MODIFY RANGE 


Supports dynamic alteration of a range. 


FORMAT MODIFY RANGE (range, | mark1, mark2 ] 
[, video_attribute ]}) 


PARAMETERS  fange ) 
The range that is to be modified. 


mark1 


A marker delimiting one end of the range. 


mark2 


A marker delimiting the other end of the range. 


video_attribute 

A keyword designating the new video attribute for the range. The 
attribute can be NONE, REVERSE, UNDERLINE, BLINK, or BOLD. 
If not specified, the video attribute for the range remains the same. 


DESCRIPTION You can use MODIFY_RANGE to specify a new starting mark and ending 
mark for an existing range. The new ending mark can be above the new 
starting mark in the buffer. 


MODIFY_RANGE can also change the characteristics of the range without 
deleting, re-creating, and repainting all the characters in the range. Using 


MODIFY_RANGE, you can direct VAXTPU to apply or remove the range’s | 


video attribute to or from characters as you select and unselect text. 


Ranges are limited to one video attribute at a time. Specifying a video 
attribute different than the present attribute causes VAXTPU to apply the 
new attribute to the entire visible portion of the range. 


If the video attribute stays the same and only the markers move, the only 
characters that are refreshed are those visible characters newly added to 
the range and those visible characters that are no longer part of the range. 


SIGNALED TPU$_NOTSAMEBUF WARNING First and d k 
a irst and second markers are in 
ERRORS different buffers. 
TPU$_ARGMISMATCH ERROR The data type of the indicated 
parameter is not supported by the 
built-in. 
TPU$_BADKEY | WARNING You specified an illegal keyword. 


\ 
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TPU$_INVPARAM ERROR You specified a parameter of the 
wrong type. 
TPU$_ MODRANGEMARKS ERROR MODIFY_RANGE requires either 
two marker parameters or none. 
TPU$_TOOFEW ERROR Too few arguments passed to the 
built-in. 
TPU$_TOOMANY ERROR Too many arguments passed to 
the built-in. 
TPU$ NORETURNVALUE ERROR The built-in cannot return a value. 
EXAMPLES For an explanation of the VAXTPU code in these examples, see the 
paragraph following each numbered code example. 
begin mark := MARK (BOLD); 
POSITION (MOUSE) ; 
finish mark := MARK (BOLD); 
this range := CREATE RANGE (begin_mark, finish_mark, BOLD); 
! ; 
Loe (User may have moved mouse) 
! : 
POSITION (MOUSE) ; 
new iwark := MARK (BOLD); 
IF new_mark <> finish_mark 
THEN 
MODIFY RANGE (this range, begin_mark, new_mark, BOLD); 
ENDIF; 
This code fragment creates a range between the editing point and the 
pointer cursor location. At a later point in the program, after which you 
might have moved the pointer cursor, the code fragment modifies the range 
to reflect the new pointer cursor location. 
MODIFY RANGE (this range, , ,BLINK); 
This statement sets the video attribute of the range this_range to BLINK. 
Notice that you must use commas as placeholders if you do not specify the 
starting and ending marks of the range. 
3} PROCEDURE move _mark (place _to_ start, direction); 


POSITION (place to start); 


IF direction = 1 
THEN 

MOVE HORIZONTAL (1); 
ELSE 

MOVE HORIZONTAL (—1) 3 
ENDIF; 


RETURN MARK (NONE) ; 
ENDPROCEDURE; 


PROCEDURE user_shrink_and_enlarge_ range 
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LOCAL start_mark, 

end mark, 
direction, 
dynamic range, 
rendition, 
remembered range; 


POSITION (LINE BEGIN) ; 
start_mark := MARK (NONE) ; 
POSITION (LINE END); 

end_mark := MARK (NONE) ; 
rendition := REVERSE; 

remembered range := CREATE RANGE 
dynamic range := 


direction := 1; 


LOOP 
UPDATE (CURRENT WINDOW) ; 


start_mark := 
end_mark := move_mark (END_OF 


MODIFY RANGE (dynamic_range, 


IF start _mark > end mark 


and Non-DECwindows Versions 


The following lines 
create a range that 
shrinks and grows and 

a range that defines 

the limits of the dynamic 
range. 


eS ee ee ee ee) 


a (start mark, end_mark, NONE); 
CREATE RANGE (start_mark, end_mark, rendition); 


! The following lines 
! shrink and enlarge 
! the dynamic range. 


move mark (BEGINNING OF (dynamic_range), direction) ; 
(dynamic range), 


1 - direction); 


start_mark, end_mark); 


rendition); 


f v 


THEN 
EXITIF READ KEY = CTRL Z KEY; 
direction := 0; 
IF rendition = REVERSE 
THEN 
rendition := BOLD; 
ELSE 
rendition := REVERSE; 
ENDIF; 
MODIFY RANGE (dynamic range, 
ENDIF; 
IF (start _mark = BEGINNING OF 


(end_mark = END OF 
THEN 
direction := 1; 
ENDIF; 
E.NNDLOOP ; 
ENDPROCEDURE; 


(remembered _range)) OR 
(remembered range) ) 


These procedures cause the range dynamic_range to shrink to one 
character, then grow until it becomes as large as the range remembered_ 


range. 
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PROC 
LOCA 


rang 


rang 


MODIFY_RANGE 


EDURE. line up characters (text_range, lined_chars_ pat) 


L 

range start, 
range end, 
temp range, 
max cols; 


6 end. i= END OF (text range); ! These statements store 
! the ends of the range 
' containing the text operated on 


e start := BEGINNING OF (text_range); 


! The following statements 
locate the portions of 

text that match the pattern 
and determine which is 
furthest to the right. 


o— «=e ome te 


max cols := Q; 


LOOP 


temp range := SEARCH QUIETLY (lined_chars pat, REVERSE, EXACT, text_range); 
EXITIF temp range = 0; 
POSITION (temp range); 
IF GET INFO (MARK (NONE), “offset _column") > max_cols 
THEN 
max cols := GET INFO (MARK (NONE), “offset _column") ; 
ENDIF; 
MOVE HORIZONTAL (-1); 
MODIFY RANGE (text range, BEGINNING OF (text_range), MARK (NONE) ); 


ENDLOOP ; 

! The following lines 

! locate matches to the 
text_range := CREATE RANGE (range start, range_end); ! pattern and align them 


LOOP 


! with the rightmost 
! piece of matching text. 


temp range := SEARCH QUIETLY (lined chars pat, FORWARD, EXACT, text range); 
EXITIF temp range = 0; 
POSITION (temp range) ; 
IF GET INFO (MARK (NONE), “offset column") < max_cols 
THEN , 
COPY TEXT (" " * (max cols - GET_INFO (MARK (NONE), "“offset_column") )); 
ENDIF; 
MOVE HORIZONTAL (1); | 
MODIFY RANGE (text _range, END_OF (text_range), MARK (NONE) ); 


ENDLOOP ; 


! Restore the range to its original state, plus a reverse attribute. 


! 


text_range := CREATE RANGE (range_start, range_end, REVERSE); ! This line 


! restores the 

! range to its 

! original state 

! and displays 

! the contents 

! in reverse video. 


ENDPROCEDURE; 
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This procedure aligns text that conforms to the pattern specified in the 
second parameter. For example, if you want to align all comments in a 
piece of VAXTPU code, you would pass as the second parameter a pattern 
defined as an exclamation point followed by an arbitrary amount of text or 
white space and terminated by a line end. 


The procedure is passed a range of text. As the procedure searches the 
range to identify the rightmost piece of text that matches the pattern, 
the procedure modifies the range to exclude any matching text. Next, the 
procedure searches the original range again and inserts padding spaces 
in front of each instance of matching text, making the text align with the 
rightmost instance of matching text. 
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POSITION (integer) 


Moves the editing point to the specified record in the current buffer. 


The POSITION built-in is supported in previous versions of VAXTPU. 
POSITION continues to perform all the functions it performed in previous 
versions; the use of POSITION to move the editing point to a specified record 
is new in the current version of VAXTPU. 


For more information about the POSITION built-in, see the VAX Text 
Processing Utility Manual. 


FORMAT 


POSITION = (integer) 


PARAMETERS 


integer 
The number of the record where you want VAXTPU to position the editing 
point. 


DESCRIPTION 


A record number indicates the location of a record in a buffer. Record 
numbers are dynamic; as you add or delete records, VAXTPU changes 

the number associated with a particular record, as appropriate. VAXTPU 
counts each record in a buffer, regardless of whether the line is visible in a 
window, or whether the record contains text. 


To position the editing point to a given record, specify the record number. 
The number can be in the range from 1 to the number of records in the 
buffer plus 1. For example, the following statement positions the editing 
point to record number 8 in the current buffer: 


POSITION (8); 
VAXTPU places the editing point on the first character of the record. 


Specifying a value of 0 has no effect. Specifying a negative number or a 
number greater than the number of records in the buffer plus 1 causes 
VAXTPU to signal an error. 


VAXTPU places the editing point on the first character in the record. 


SIGNALED 
ERRORS 


TPU$_ARGMISMATCH ERROR Wrong type of data sent to the 
built-in. 
TPU$_BADVALUE ERROR You specified a record number 


less than O or greater than the 
length of the buffer plus 1. 


TPU$_TOOFEW ERROR Too few arguments passed to the 
| built-in. 
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TPU$_TOOMANY ERROR Too many arguments passed to 
| the built-in. 
EXAMPLE The following statement moves the editing point to the tenth line in the 


current buffer. 
POSITION (10); 


For an example of a procedure using the POSITION (integer) built-in, see 
Example 7-8. . 
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POSITION (MOUSE) 


Positions the editing point to the location indicated by the pointer cursor. 


The POSITION built-in is supported in previous versions of VAXTPU. 
POSITION continues to perform all the functions it performed in previous 
versions; the fact that POSITION (MOUSE) can be used in contexts other 
than programs bound to mouse keys is new in DECwindows VAXTPU. 


FORMAT 


POSITION (MOUSE) 


PARAMETERS MOUSE 


A keyword directing VAXTPU to associate the editing point with the 
location of the pointer cursor. 


DESCRIPTION 


In the DECwindows version of VAXTPU, you can use the statement 
POSITION (MOUSE) at any point after the first keyboard or mouse 
button event. The statement positions the editing point to the location 
occupied by the pointer cursor at the time of the most recent keyboard or 
mouse-button event. 


If the pointer cursor is on a window’s status line when POSITION 
(MOUSE) is executed, VAXTPU positions the editing point at the line 
just above the status line. 


If the pointer cursor is not located in a VAXTPU window at the time of 
the most recent keyboard or mouse-button event, POSITION (MOUSE) 
returns the status TPU$_NOWINDOW. 


SIGNALED 
ERRORS 


TPU$_BADKEY WARNING You specified an invalid keyword 
as a parameter. 

TPU$_INVPARAM ERROR One of the parameters was 
specified with data of the wrong 
type. 

TPU$_TOOFEW ERROR Too few arguments passed to the 
built-in. 

TPU$_TOOMANY ERROR Too many arguments passed to 
the built-in. 

TPU$_NOWINDOW WARNING _ The pointer cursor was not located 


in a VAXTPU window at the time 
of the most recent keyboard or 
mouse-button event. 
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SET (KEY MAP LIST) 


Associates the named key map list with the specified window. 


SET (KEY_MAP_LIST) is supported in previous versions of VAXTPU. The 
built-in continues to behave as it did in previous versions. The fact that you 
can associate a key map list with a window supplements the fact that you can 
associate a key map list with a buffer. 


For more information about the SET (KEY_MAP_LIST) built-in, see the VAX 
Text Processing Utility Manual. 


FORMAT SET (KEY MAP _LIST, string, window) 


PARAMETERS KEY_MAP _LIST 


A keyword used. to establish a key map list. 
string 


The name of the key map list you want to associate with a window. 


window 
The window with which you want to associate the key map list. 


DESCRIPTION _ The key map list manipulated by this built-in is used only to process 
mouse events in the specified window. Keystrokes are processed with the 
key map list associated with the buffer. 


SIGNALED TPU$_NOKEYMAPLIST WARNING _ Attempt t defined 
= empt to access an undefine 
ERRORS key map list. 
TPU$_TOOFEW ERROR Too few arguments passed to the 
built-in. 
TPU$_TOOMANY ERROR Too many arguments passed to 
the built-in. 
TPU$_NOCURRENTBUF ERROR You are not positioned in a buffer. 
TPU$_INVPARAM ERROR Wrong type of data sent to the 
built-in. 
EXAMPLE The following procedure creates a small "scratch pad" window and maps 


it to a scratch buffer called junk1l.ixt. The procedure defines a key map list 
consisting of a user-define key map redefining M1DRAG plus the standard 
EVE mouse key map. By setting the scratch window’s key map list to be 
user_scratch_list, the procedure invokes sample_m1_drag when the user 
drags the mouse in the scratch window. 
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PROCEDURE user _scratch_window 


LOCAL scratch window, 
scratch. Durter, 
scratch map, 
Scratch, hast; 


scratch window := CREATE WINDOW (20, 3, ON); 
scratch butter := CREATE BUFFER. ("test "Junk Jtxe"); 
scratch map := CREATE KEY MAP ("user scratch_map"); 


DEFINE KEY (eve$$kt_return + "sample Ml DRAG", MIDRAG, "mouse button_1", 
"user scratch map"); 
scratch list := CREATE KEY MAP LIST ("user scratch list", "user scratch map", 
eveSx mouse keys); 
SET (KEY MAP LIST, "user scratch list", scratch window); 
MAP (scratch window, scratch buffer); 


ENDPROCEDURE; 
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SET (MODIFIED) 


Turns on or turns off the bit indicating that the specified buffer has been 
modified. 


FORMAT ON 
SET (MODIFIED, butter, { cone \ 


PARAMETERS MODIFIED 
A keyword directing VAXTPU to turn on or turn off the indicator 
designating a buffer as modified. 


buffer 
The buffer whose indicator you want to control. 
ON | 
A keyword directing VAXTPU to mark a buffer as modified. 
OFF 
A keyword directing VAXTPU to mark a buffer as unmodified. 
SIGNALED TPU$_BADKEY WARNING  Y ified an invalid k d 
x ou specified an invalid keywor 
ERRORS as a parameter. 
TPU$_INVPARAM ERROR One of the parameters was 
specified with data of the wrong 
type. 
TPU$_NORETURNVALUE ERROR The built-in cannot return a value. 
TPU$_TOOFEW ERROR Too few arguments passed to the 
built-in. 
TPU$_TOOMANY ERROR Too many arguments passed to 
the built-in. 
EXAMPLE The following statement marks the current buffer as modified: 


SET (MODIFIED, CURRENT BUFFER, ON); 
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SET (MOUSE) 


Assigns the keyword ON or OFF to the return variable you specify. 


The SET (MOUSE) built-in is supported in the version of VAXTPU released 
with VMS Version 5.0. SET (MOUSE) continues to perform all the functions it 
performed in previous versions; the return values ON and OFF are new in this 
version of VAXTPU. : 


For more information on the SET (MOUSE) built-in, see the VAX Text 
Processing Utility Manual. 


FORMAT E{ON \:21seT (mouse, { ON \) 


ae 


DESCRIPTION The return value specifies whether VAXTPU mouse support was enabled 
or disabled before the current SET (MOUSE) statement was executed. 
This allows you to enable or disable mouse support and then reset the 
support to its previous setting without having to make a separate call. 


SIGNALED TPU$_BADKEY WARNING = Thek d t be either ON 
e keyword must be either or 
ERRORS 7 eee 
TPU$_MOUSEINV WARNING You have tried to enable mouse 
support on an incompatible 
terminal. 
TPU$_INVPARAM ERROR One or more of the specified 
parameters have the wrong type. 
TPU$_TOOFEW ERROR SET (MOUSE) requires two 
parameters. 
TPU$_TOOMANY ERROR You specified more than two 
parameters. 
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SET (SCREEN_UPDATE) 


Returns a variable of tyoe KEYWORD indicating whether screen updating was 
enabled or disabled before the current SET (SCREEN _UPDATE) statement 
was executed. 


The SET (SCREEN_UPDATE) built-in is supported in the version of VAXTPU 
released with VMS Version 5.0. SET (GCREEN_UPDATE) continues to 
perform all the functions it performed in previous versions; the fact that it 
allows a return value of tyoe KEYWORD is new in this version of VAXTPU. 


For more information about this built-in, see the VAX Text Processing Utility 


Manual. 
FORMAT ON ).. ON 
T{ id \ i= SET (SCREEN_UPDATE, { nl \) 


PARAMETERS SCREEN_ UPDATE 
A keyword directing VAXTPU to set an attribute of screen updating. 


ON 
A keyword indicating that screen updating is enabled. 


OFF 


A keyword indicating that screen updating is disabled. 


return value A variable containing the keyword value ON or OFF. The keyword specifies 
whether VAXTPU screen updating support was enabled or disabled before 
the current SET (SCREEN_UPDATE) statement was executed. Using the 
returned variable, you can enable or disable screen updating and then 
reset the support to its previous setting without having to make a separate 
call to fetch the previous setting. 


SIGNALED TPU$_BADKEY WARNING  Thek d t be ON or OFF. 
e keyword must be or 
ERRORS : : . 
TPU$_INVPARAM ERROR One or more of the specified 
parameters have the wrong type. 
TPU$_TOOFEW ERROR SET (SCREEN_UPDATE) requires 
two parameters. 
TPU$_TOOMANY ERROR You specified more than two 
parameters. 
TPU$_UNKKEYWORD ERROR You have specified an unknown 
keyword. 
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STR 


Accepts a string as a parameter without generating an error; also has a new 
optional parameter. 


The STR built-in is supported in previous versions of VAXTPU. STR continues 
to perform all the functions it performed in previous versions; the string1 
parameter and the keywords ON and OFF are new in this version of VAXTPU. 


For more information about the STR built-in, see the VAX Text Processing 
Utility Manual. 


FORMAT buffer . , ON 
str3:=STR ( range \f es J OFF | ) 
string 1 


PARAMETERS buffer 


The buffer whose contents you want returned as a string. 


range 


The range whose contents you want returned as a string. 


string1 

Any string. STR now accepts a parameter of type STRING, so you need 
not check the type of the parameter you supply to the built-in. If you 
specify a parameter of type STRING, you cannot use either of the optional 
parameters. 


string2 

A string specifying how you want line ends represented. The default is the 
null string. You can only use string2 if you specify a range or buffer as the 
first parameter. If you want to specify the keyword ON or OFF but do not 
want to specify string2, you must use a comma before the keyword as a 
placeholder, as follows: 


new string := STR (old _ buffer, , ON); 


ON 


A keyword directing VAXTPU to insert spaces preserving the white space 
created by the left margin of each record in the specified buffer or range. 
Specifically, if you specify a buffer or range with a left margin greater than 
1, the keyword ON directs VAXTPU to insert a corresponding number of 
spaces after the line-ends in the resulting string. For example, if the left 
margin of the specified lines is 10 and you use the keyword ON, VAXTPU 
inserts 9 spaces after each line-end in the resulting string. VAXTPU 

does not insert any spaces after line-begins of lines that do not contain 
characters. If the first line of a buffer or range starts at the left margin, 
VAXTPU inserts spaces before the text in the first line. 
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Note that you can only use this keyword if you specify a buffer or range as 
a parameter. | : _ 


OFF 

A keyword directing VAXTPU to ignore the left margin setting of the 
records in the specified buffer or range. This is the default. For example, 
if the left margin of the specified lines is 10 and you use the keyword OFF, 


VAXTPU does not insert any spaces after the line-ends in the resulting 
string. 


Note that you can only use this keyword if you specify a buffer or range as 
a parameter. | 


return value 
str3 The string equivalent of the parameter you specify. 


SIGNALED TPU$_TRUNCATE WARNING iY ified a buff 
ee ou specified a buffer or range 
ERRORS so large that converting it would 
exceed the maximum length for 
a string. VAXTPU has truncated 
characters from the returned 
string. 

TPU$_NEEDTOASSIGN ERROR STR must appear on the right- 
hand side of an assignment 
statement. 

TPU$_TOOFEW ERROR STR requires at least one 
argument. 


TPU$_TOOMANY ERROR STR accepts only two arguments. 
TPU$_INVPARAM ERROR The argument to STR must be an 
integer, buffer, string, or range. 


TPU$_STRTOOLARGE ERROR The resulting string contains more 
than 65,535 characters. 


EXAMPLES 


| return_string := STR (SELECT RANGE, "<CRLF>", ON); 


This statement creates a string using the text in the select range. Line 
breaks are marked with the string CRLF. The white space created by the 
margin is preserved by inserting spaces after the line breaks. 


2 still_a_string := STR ("confetti"); 


This statement assigns the string confetti to the variable still_a_string. 
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This chapter describes the new DECwindows-related built-in procedures 
in VAXTPU Version 2.2. For information about the new and modified 
built-ins that are common to both the DECwindows and non-DECwindows 
versions of VAXTPU, see Chapter 4. For information about the VAXTPU 
built-ins released before VMS Version 5.1, see the VAX Text Processing 
Utility Manual. For an overview of recent VAXTPU release history and 
version numbering, see Chapter 1. 


Viewing Examples of Code Using Built-In Procedures 


To see examples of how a layered application uses various VAXTPU built- 
ins, you can view some of the files used to create the EVE editor. To see a 
directory of the files available, type the following command from the DCL 
command line: 


S DIR SYSSEXAMPLES: EVES *.TPU 


These files contain procedures using almost all of the new and modified 
built-ins. 


Descriptions of Built-In Procedures 


This section describes the DECwindows VAXTPU built-in procedures 
that have been added in VAXTPU Version 2.2. The built-ins are listed 
alphabetically. 


Using the new and modified built-ins, you can perform the following tasks: 
¢ Create and manipulate widgets 

e Enable, disable, and manipulate scroll bars 

e Use the DECwindows clipboard with VAXTPU 

¢ Use DECwindows global selection with VAXTPU 

¢ Manipulate input focus 


¢ Convert pixel-oriented information to character-cell-oriented 
information and the reverse 


e Support mouse operations needed in a DECwindows environment 
e Resize the VAXTPU screen 


e Specify the application name that appears in the DECwindows icon 
box 


For more information about using VAXTPU built-ins, see the VAX Text 
Processing Utility Manual. 
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CREATE WIDGET 


Creates a widget instance. The CREATE_WIDGET built-in has two variants 
with separate syntaxes. One variant creates and returns a widget using the 
intrinsics or an XUI Toolkit low-level creation routine. The other variant creates 
an entire hierarchy of widgets (as defined in an XUI Resource Manager 
database) and returns the topmost widget. 


FORMAT widget := CREATE WIDGET 
(widget_class, widget_name, 
eee widget i 

SCREEN 

, buffer 

, learn_sequence 
[, § , program 

, range 

, string 
[, closure 
[, widget_args ] J ]) 


DESCRIPTION — Creates the widget instance you specify, using the intrinsics or an XUI1 
Toolkit low-level creation routine. Although it has been created, the 
returned widget is not managed and therefore not visible. The application 
must call the MANAGE_WIDGET built-in to make the widget visible. 


FORMAT widget := CREATE_WIDGET 
(resource_manager_name, hierarchy_id, 
oe widget 

SCREEN 
, buffer — 
| , learn_sequence 
[, < , program 
, range 
, string 
[, closure | 
[, widget_args ] J ]) 
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DESCRIPTION 


Creates and returns an entire hierarchy of widgets (as defined in an XUI 
Resource Manager database) and returns the topmost widget. All children 
of the returned widget are also created and managed. The topmost widget 
is not managed, so none of the widgets created is visible. 


If you specify one or more callback arguments in your User Interface 
Language (UIL) file, specify either the routine TPUS$SWIDGET_INTEGER_ 
CALLBACK or the routine TPU$WIDGET_STRING_CALLBACK. 

For more information about specifying callbacks, see Chapter 6. For 
more information about UIL files, see the VMS DECwindows Guide to 
Application Programming. 


When you use CREATE_WIDGET to create a widget or hierarchy of 
widgets organized by the XUI Resource Manager, CREATE_WIDGET uses 
the XUI Toolkit routine FETCH WIDGET. 


PARAMETERS 


widget_class 
The integer returned by DEFINE_WIDGET_CLASS that specified the 
class of widget to be created. 


widget_name 
A string that is the name to be given to the widget. 


parent_widget 
The widget that is to be the parent of the newly created widget. 


SCREEN 


A keyword indicating that the newly created widget is to be the child of 
VAXTPU’s main window widget. 


buffer 

The buffer containing the interface callback routine. This code is executed 
when the widget performs a callback to VAXTPU; all widgets created with 
a single CREATE_WIDGET call use the same callback code. If you do not 
specify this parameter, VAXTPU does not execute any callback code when 
the widget performs a callback to VAXTPU. 


learn_sequence 

The learn sequence that is the interface callback routine. This is executed 
when the widget performs a callback to VAXTPU; all widgets created with 
a single CREATE_WIDGET call use the same callback code. If you do not 
specify this parameter, VAXTPU does not execute any callback code when 
the widget performs a callback to VAXTPU. 


program 

The program that is the interface callback routine. This is executed when 
the widget performs a callback to VAXTPU; all widgets created with a 
single CREATE_WIDGET call use the same callback code. If you do not 
specify this parameter, VAXTPU does not execute any callback code when 
the widget performs a callback to VAXTPU. 
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return value 


range 

The range containing the interface callback routine. This is executed when 
the widget performs a callback to VAXTPU; all widgets created with a 
single CREATE_WIDGET call use the same callback code. If you do not 
specify this parameter, VAXTPU does not execute any callback code when 
the widget performs a callback to VAXTPU. 


string 

The string containing the interface callback routine. This is executed 
when the widget performs a callback to VAXTPU; all widgets created with 
a single CREATE_WIDGEHT call use the same callback code. If you do not 
specify this parameter, VAXTPU does not execute any callback code when 
the widget performs a callback to VAXTPU. 


closure 

A string or integer. VAXTPU passes the value to the application when the 
widget performs a callback to VAXTPU. For more information about using 
closures, see Chapter 6. If you do not specify this parameter, VAXTPU 
passes the closure value (if any) given to the widget in the UIL file 
defining the widget. If you specify the closure value with CREATE_ 
WIDGET instead of in the UIL file, all widgets created with the same 
CREATE_WIDGET call have the same closure value. 


widget_args 

A series of pairs of resource names and resource values. You can specify a 
pair in an array or as a pair of separate parameters. If you use an array, 
you index the array with a string that is the name of the resource you 
want to set. The array element contains the value you want to assign to 
that resource. If you use a pair of separate parameters, use the following 
format: 


resource name_string, resource value 


Arrays and string/value pairs may be used together. Each array index 
and its corresponding element value, or each string and its corresponding 
value, must be valid widget arguments for the class of widget you are 
creating. 


resource_manager_name 
A case-sensitive string that is the name assigned to the widget in the UIL 
file defining the widget. 


hierarchy_id 

The hierarchy identifier returned by the SET (DRM_HIERARCHY) built- 
in. This identifier is passed to the XUI Resource Manager, which uses the 
identifier to find the resource name in the database. 


The newly created widget instance. 


DESCRIPTION 


The case of a widget’s name in the User Interface Definition (UID) file 
must match the case of the widget’s name that you specify as a parameter 
to CREATE_WIDGET. If you specify case-sensitive widget names in 

your UIL file, you must use the same widget name case with CREATE_ 
WIDGET as you used in the UIL file. If you specify case-insensitive widget 
names in your UIL file, the UIL compiler translates all widget names to 
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uppercase, so in this instance you must use uppercase widget names with 
CREATE_WIDGET. The example in the following section specifies case- 
insensitive widget names in the UIL file and specifies an uppercase name 
for the widget with the CREATE_WIDGET built-in. 


SIGNALED TPU$_BADKEY WARNING Y ified an invalid k d 
= ou specified an invalid keywor 
ERRORS as a parameter. 

TPU$_UNDWIDCLA WARNING ~~ You have specified a widget 
class integer that is not known to 
VAXTPU. 

TPU$_INVPARAM ERROR One of the parameters was 
specified with data of the wrong 
type. 

TPU$_NEEDTOASSIGN ERROR The built-in must return a value. 

TPU$_REQSDECW ERROR You can use the built-in only if the 
DECwindows screen updater is in 
use. 

TPU$_TOOFEW ERROR Too few arguments passed to the 
built-in. 

TPU$_TOOMANY ERROR Too Many argumenis passed io 
the built-in. 

TPU$_WIDMISMATCH ERROR You have specified a widget whose 
class is not supported. 

EXAMPLES For an explanation of the code in these examples, see the paragraph 
following each numbered code example. 
H | PROCEDURE eve_ display example 


LOCAL example widget, 
example widget name, 


Variable assigned to the created widget. 
The name of the widget assigned 

to this variable must be uppercase 

if you specified case-insensitive 

widget names in the UIL file. 


o— 0mm bem em Ome 


example hierarchy; ! XUI Resource Manager 
! hierarchy for this example. 


ON ERROR 
[OTHERWISE] : ! Traps errors. 
ENDON_ERROR; 


! Set the widget hierarchy. The default file spec is "SYSSLIBRARY: .UID" 
example hierarchy := SET (DRM HIERARCHY, "mynodeSdua0: [smith] example") ; 


! The VAXTPU CREATE WIDGET built-in needs the name of the widget 
i Cetined in. the-Uli file, 


example widget _name = "EXAMPLE BOX"; ! The widget EXAMPLE BOX is 
! defined in the file EXAMPLE.UIL. 


' Create the widget if it has not already been created. 
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IF GET INFO (example widget, "type") <> WIDGET 
THEN 
example widget := CREATE WIDGET (example widget name, example hierarchy, 
_ SCREEN, "“eveSkt_callback_routine") ; 


! EVE defines eveSkt_ callback routine to be EVE’s callback routine. 
! You do not need to define it again if you are extending EVE. 


ENDIF; 

! Map "example widget" to the screen using MANAGE WIDGET. 
MANAGE WIDGET (example widget) ; 

RETURN (TRUE) ; 

ENDPROCEDURE; 


This procedure, eve_display_example, creates a modal dialog box widget 
and maps the widget to the VAXTPU screen. 


The procedure shows how to use the variant of CREATE_WIDGET 
that returns an entire widget hierarchy. To create a widget or widget 
hierarchy using this variant, you must have available the compiled form 
of a User Interface Language (UIL) file specifying the characteristics of 
the widgets you want to create. DIGITAL recommends that you use one 
or more UIL files and the corresponding variant of CREATE_WIDGET 
whenever possible, because UIL is more efficient and because UIL files 
make it easier to translate your application into other languages. For 
more information about compiling and using UIL files, see the VMS 
DECwindows Guide to Application Programming. 


2 MODULE example 
VERSION = ’V00-000’ 


! This is a sample UIL file that creates a modal dialog box containing 
' the message "Hello World." | 


NAMES = case insensitive 


PROCEDURE 

tpuSwidget_integer callback (integer) ; 
VALUE 

example callback : Le 

example button label > ‘Acknowledged’ ; 

example message : ‘Hello World’; 
OBJECT 


example box : message box { 


arguments { 
default position = true; ! puts box in center work area 
ok label = example button_label; 
label label = example message; 
be 
be 


END MODULE; 


This example shows a sample UIL file describing the modal dialog box 
called example_box. The UIL file specifies where the widget appears on 
the screen, what label appears on the box’s button, and what message the 
widget displays. 
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For an example showing how to use the variant of CREATE_WIDGET that 
calls the XUI Toolkit low-level creation routine, see Example 7-2. 
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DEFINE WIDGET CLASS 


Defines a widget class for later use in creating widgets of that class using the 
DECwindows intrinsics or the XUI Toolkit low-level creation routines. 


FORMAT integer := DEFINE_WIDGET CLASS 
(class_name 
[, creation_routine_name 
I, creation_routine_image_name ] J) 


PARAMETERS'- class_name 


A string that is the name of a universal symbol pointing to the desired 
widget class record. A universal symbol is a symbol in a shareable image 
that can be referred to in an image other than the one in which the symbol 
is defined. 


creation_routine_name 

A string that is the name of the low-level widget creation routine for this 
widget class. Specify the case of the string correctly. To determine the 
correct case of the string, consult the documentation for the widget whose 
class you are defining. The current version of VAXTPU, which is bundled 
with the VMS operating system, ignores the case of the string. However, 
future versions of VAXTPU may treat the string as case-sensitive. 


If you do not specify this parameter, VAXTPU uses the XUI Toolkit 
CREATE WIDGET routine to create the widget instead of using a low- 
level widget creation routine. The routine must have the same calling 
sequence as the XUI Toolkit low-level widget creation routines. 


creation_routine_image_name 

A string that is the name of the shareable image in which the class 
record can be found. If you specify a low-level creation routine, DEFINE_ 
WIDGET_CLASS also looks for the routine in the program image. If 
you do not specify an image, VAXTPU assumes the widget is defined in 
SYS$LIBRARY:DECW$DWTLIBSHR.EXE. 


return value An integer used to identify the class of widget to be created by the 
CREATE_WIDGET built-in. 


DESCRIPTION _ Each call returns a different class integer, which you use to specify the 
class of a widget when you create it. 
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SIGNALED TPU$_ARGMISMATCH ERROR The data t f the indicated 
z e data type of the indicate 
ERRORS parameter is not supported by the 
built-in. 
TPU$ NEEDTOASSIGN ERROR The built-in must return a value. 
TPU$_TOOFEW ERROR Too few arguments passed to the 
built-in. 
TPU$_TOOMANY ERROR Too many arguments passed to 
the built-in. 
TPU$_REQSDECW ERROR You can use the built-in only if the 
DECwindows screen updater is in 
use. 
EXAMPLE For a sample procedure using the DEFINE_WIDGET_CLASS built-in, see 
Example 7-2. 
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DELETE (widget) 


Deletes the specified widget instance and its children. 


The DELETE built-in is supported in previous versions of VAXTPU. DELETE 
continues to perform all the functions it performed in previous versions; the 
use of DELETE to delete widgets is new in DECwindows VAXTPU. 


For more information on the DELETE built-in, see the VAX Text Processing 
Utility Manual. 


FORMAT DELETE (widget) 


PARAMETERS widget 
The widget to be deleted. 


| When you use the DELETE (widget) builtin, all variables and array | 


DESCRIPTION | 
elements that refer to the widget are set to UNSPECIFIED. If an array 
element is indexed by the deleted widget, the array element is deleted as 
well. 
SIGNALED TPU$_TOOFEW ERROR DELETE requires one argument 
requi 
ERRORS : : : 
TPU$_TOOMANY ERROR DELETE accepts only one 
argument. 
TPU$_BADDELETE ERROR You attempted to delete a 
constant. 
EXAMPLE The following code fragment creates a modal dialog box widget and later 


deletes it. For purposes of this example, the procedure user_callback_ 
dispatch_routine is assumed to be a user-written procedure that handles 
widget callbacks. For a sample DECwindows User Interface Language 
(UIL) file to be used with VAXTPU code creating a modal dialog box 
widget, see the example in the description of the CREATE_WIDGET 
built-in. 


PROCEDURE sample create _and delete 


LOCAL example widget, 
example widget _name, 
example hierarchy; 
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| DELETE (widget) 


example hierarchy := SET (DRM HIERARCHY, "mynodeSdua0: [smith]example.uid") ; 
:= "EXAMPLE BOX"; | 


example widget name 
example widget := CREATE WIDGET (example widget_name, 
example hierarchy, SCREEN, 


"user callback dispatch_routine") ; 


DELETE (example widget) ; 


ENDPROCEDURE; 
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GET CLIPBOARD 


Reads STRING format data from the clipboard and returns a string containing 


this data. 
FORMAT string := GET_CLIPBOARD 
return value A string consisting of the data read from the clipboard. Line breaks are 


indicated by a line-feed character (ASCII (10)). 


DESCRIPTION  DECwindows provides a clipboard that allows you to move data between 
applications. Applications can write to the clipboard to replace previous 
data, and can read from the clipboard to get a copy of existing data. The 
data in the clipboard may be in multiple formats, but all the information 
in the clipboard must be written at the same time. 


VAXTPU provides no clipboard support for applications not written for 


DECwindows. 
SIGNALED TPU$_NEEDTOASSIGN ERROR The built-i t ret | 
e built-in must return a value. 
ERRORS 7 
TPU$_TOOMANY ERROR Too many arguments passed to 
the built-in. 
TPU$_CLIPBOARDFAIL WARNING _ The clipboard has not returned 
any data. 


TPU$_CLIPBOARDLOCKED WARNING VAXTPU cannot read from the 
clipboard because some other 
application has locked it. 

TPU$_CLIPBOARDNODATA WARNING _ There is no STRING format data 
in the clipboard. 


TPU$_ TRUNCATE WARNING Characters have been truncated 
because you tried to add text that 
would’ exceed the maximum line 
length. 


TPU$_STRTOOLARGE ERROR The amount of data in the 
clipboard exceeds 65,535 
characters. 


TPU$_REQSDECW ERROR You can use the built-in only if the 
, DECwindows screen updater is in 
use. 
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GET CLIPBOARD 


EXAMPLE The following statement reads what is currently in the clipboard and 
assigns it to new_string: 


the string := GET CLIPBOARD; 


For an example of a procedure using the GET_CLIPBOARD built-in, see 
Example 7-3. 
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GET DEFAULT 


Returns the value of an X resource from the X resources database. 


FORMAT string3 


sir \ ss GET DEFAULT (string1, string2) 


PARAMETERS _ string? 
The name of the resource whose value you want GET_DEFAULT to fetch. 
Note that resource names are case-sensitive. 


string2 
The class of the resource. Note that resource class names are case- 
sensitive. 


return value The string equivalent of the resource value or 0 if the specified resource 
is not defined. Note that, if necessary, the application must convert the 
string to the data type appropriate to the resource. 


DESCRIPTION i GET_DEFAULT is useful for initializing a layered application that uses 
an X defaults file. You can use the built-in only in the DECwindows 


environment. 
SIGNALED TPU$_INVPARAM ERROR One of th t 
isi ne of the parameters was 
ERRORS | specified with data of the wrong 
| type. 
TPU$_TOOFEW ERROR Too few arguments passed to the 
built-in. 
TPU$_TOOMANY ERROR Too many arguments passed to 
the built-in. 
TPU$_NEEDTOASSIGN ERROR The built-in must return a value. 
TPU$_REQSDECW ERROR You can use the built-in only if the 
DECwindows screen updater is in 
use. 
EXAMPLE If you want to create an extension of EVE that enables use of an X defaults 


file to choose a keypad setting, you can use a GET_DEFAULT statement 
in a module_init procedure. For more information about extending EVE 
using a module_init procedure and the EVE$BUILD tool, see the VAX Text 
Processing Utility Manual. 
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GET DEFAULT 


The following code fragment shows the portion of a module_init procedure 
directing VAXTPU to fetch the value of a resource from the X resources 
database. 

PROCEDURE application module init 


LOCAL 
keypad name; 


keypad _ name := GET DEFAULT ("user.keypad", "User.Keypad") ; 
EDIT (keypad name, UPPER); ! Convert the returned string to uppercase. 


IF keypad name <> ’0’ 
THEN 


CASE keypad name 


* ED > eve set _ keypad_edt (); 
"NOEDT" : eve set _ keypad noedt (); 
"WPS" >: eve set_keypad_wps (); 
“NOWPS" > eve _set_keypad_nowps (); 
"NUMERIC" : eve_set_keypad_ numeric (); 
oVELOO™ >: eve set_keypad vt100 (); 
[INRANGE, OUTRANGE] : eve _set_keypad_ numeric; ! If user has 
! used invalid value, 
! set the keypad to 
! NUMERIC setting. 
ENDCASE; 
ENDIF; 
ENDPROCEDURE; 


To provide a value for the GET_DEFAULT statement to fetch, an X 
defaults file would contain an entry similar to the following: 


User.Keypad : EDT 
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GET GLOBAL SELECT 


Supplies information about a global selection. 


FORMAT unspecified 
string := GET GLOBAL SELECT 
integer 
array 
PRIMARY 


(} SECONDARY _ }, selection_property_name) 
selection_name 


PARAMETERS PRIMARY 


A keyword indicating the layered application is requesting information 
about a property of the primary global selection. 


SECONDARY 


A keyword indicating the layered application is requesting information 
about a property of the secondary global selection. 


selection_name 

A string identifying the global saicetioa whose property is the subject of 
the layered application’s information request. Specify the selection name 
as a string if the layered application needs information about a selection 
other than the primary or secondary global selection. 


selection_property_name 
A string specifying the property whose value the layered application is 


requesting. 
return value 

unspecified A data type indicating that the information requested by the 
layered application was not available. 

string The value of the specified global selection property. The 
return value is of type STRING if the value of the specified 
global selection property is of type STRING. 

integer The value of the specified global selection property. The 
return value is of type INTEGER if the value of the specified 
global selection property is of type INTEGER. 

array An array passing information about a global selection 


whose contents describe information that is not of a data 
type supported by VAXTPU. For example, the array could 
return information about a pixmap, an icon, or a span. 
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GET _GLOBAL_SELECT 


VAXTPU does not use or alter the information in the array; 
the application layered on VAXTPU is responsible for 
determining how the information is used, if at all. Since the 
array is used to receive information from other DECwindows 
applications, all applications that exchange information 
whose data type is not supported by VAXTPU should adopt 
a convention on how the information is to be used. 


The element array {0} contains a string naming the data 
type of the information being passed. For example, if the 
information being passed is a span, the element contains 
the string "SPAN". The element array {1} contains either 
the integer 8, indicating that the information is passed as 
a series of bytes, or the integer 32, indicating that the 
information is passed as a series of longwords. If array 
{1} contains the value 8, the element array {2} contains 

a string and there are no array elements after array {2}. 
The string does not name anything, but rather is a series 
of bytes of information. As mentioned, the meaning and 
use of the information is agreed upon by convention 
among the DECwindows applications. To interpret this 
string, the application can use the SUBSTR built-in to 
obtain substrings one at a time, and the ASCII built-in to 
convert the data to integer format if necessary. For more 
Information about using these VAXTPU eiemenis, see the 
VAX Text Processing Utility Manual. 


If array {1} contains the value 32, the element array {2} 
contains an integer. In this case, the array can have any 
number of elements after array {2}. These elements are 
numbered sequentially beginning at array {3}. All the 
elements contain integers. Each integer represents a 
longword of data. To determine how many longwords are 
being passed, an application can determine the length of 
the array and subtract 2 to allow for elements array {0} and 
array {1}. 


DESCRIPTION _ If an owner for the global selection exists, and if the owner provides the 
information requested in a format that VAXTPU can recognize, GET_ 
GLOBAL_SELECT returns the information. 


SIGNALED 


TPU$_ARGMISMATCH ERROR Wrong type of data sent to the 
ERRORS le 


built-in. 


TPU$ NEEDTOASSIGN ERROR The built-in must return a value. 


TPU$_INVPARAM 


TPU$S_REQSDECW 


ERROR One of the parameters was 
specified with data of the wrong 
type. 

ERROR You can use the built-in only if the 
DECwindows screen updater is in 
use. 
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TPU$_TOOFEW ERROR _ Too few arguments passed to the 
| | built-in. 
TPU$_TOOMANY ERROR Too many arguments passed to 
| the built-in. 
TPU$_GBLSELOWNER WARNING ~~ VAXTPU owns the global 
selection. 
TPU$_BADKEY WARNING . You specified an invalid keyword 
3 as a parameter. 
TPU$_INVGBLSELDATA WARNING _ The global selection owner 
provided data that VAXTPU cannot 
process. 
TPU$_NOGBLSELDATA WARNING _ The global selection owner has 


indicated that it cannot provide the 
information requested. 


TPU$_NOGBLSELOWNER WARNING You have requested information 
about an unowned global 


selection. 

TPU$_TIMEOUT WARNING _ The global selection owner did not 
respond before the timeout period 
expired. 

EXAMPLE The following statement fetches the text in the primary global selection 


and assigns it to the variable string_to_paséte. 
string to paste := GET GLOBAL SELECT (PRIMARY, "STRING") ; 


For another example of how to use the GET_GLOBAL_SELECT built-in, 
see Example 7—4. 
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GET_INFO (buffer_variable, "read routine") 


Returns the global selection read routine. 


For more information about the GET_INFO built-in, see the VAX Text 
Processing Utility Manual. 


FORMAT integer cet INFO. ({ ber 
program ‘= 4 | 
learn sequence SCREEN 

"read_routine", 
GLOBAL_SELECT) 


PARAMETERS _ buffer 


The buffer with which the global selection read routine is to be associated. 


SCREEN 
A keyword directing VAXTPU to return the application’s default global 
selection read routine. 


"read_routine” 


A string indicating that the built-in is to return a read routine. 


GLOBAL_SELECT 


A keyword indicating that the built-in is to return the global selection read 


routine. 
return value 
integer The value 0 if a global selection read routine has not been 
set for either the buffer or the application. 
program The program implementing the global selection read routine 
for either the buffer or the application. 
learn_sequence The learn sequence implementing the global selection read 


routine for either the buffer or the application. 


DESCRIPTION _ Returns the program or learn sequence that VAXTPU executes when it 
owns a global selection and another application has requested information 
about that selection. If the application has not specified a global selection 
read routine, 0 is returned. 


The first parameter indicates whether the application is asking for the 
buffer-specific read routine or the application’s default read routine. 
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GET_INFO (key_name, "key_modifiers") 


Fetches information about the specified key name. 


For more information about the GET_INFO built-in, see the VAX Text 
Processing Utility Manual. 


FORMAT integer :=GET_INFO (key_name, "key_modifiers") 


PARAMETERS key_name 
A VAXTPU keyword that is a valid name for a key. 


"key_modifiers" 

A string directing VAXTPU to return a bit-encoded integer indicating what 
key modifier or modifiers have been used to create the VAXTPU key name 
specified by the parameter key_name. 


return value A bit-encoded integer indicating what key modifier or modifiers have been 
used to create the VAXTPU key name specified by the parameter key_ 
name. 


DESCRIPTION _ Returns a bit-encoded integer indicating what key modifier or modifiers 
have been used to create the VAXTPU key name specified by the 
parameter key_name. For more information about the meaning and 
possible values of key modifiers, see the description of the KEY_NAME 
built-in in this chapter. 


VAXTPU defines four constants to be used when referring to or testing 
the numerical value of key modifiers. The correspondence between key 
modifiers, defined constants, and bit-encoded integers is as follows: 


Corresponding 


Key Modifier Keyword Corresponding Constant Bit-Encoded Integer 
SHIFT_MODIFIED TPU$K_SHIFT_MODIFIED 1 
CTRL_MODIFIED TPU$K_CTRL_MODIFIED 2 
HELP_MODIFIED TPU$K_HELP_MODIFIED 4 
ALT_MODIFIED TPU$K_ALT_MODIFIED 8 


Note that the keyword SHIFT_KEY may have been used to create a 
VAXTPU key name. SHIFT_KEY is not a modifier, it is a prefix. The 
SHIFT key, also called the GOLD key by the EVE editor, is pressed and 
released before any other key is pressed. In DECwindows, modifying keys 
such as the CTRL key are pressed and held down while the modified key 
is pressed. 
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Note, too, that if more than one key modifier was used with the KEY_ 
NAME built-in, the value of the returned integer is the value of the sum of 
the integer representations of the key modifiers. For example, if you create 
a key name using the modifiers HELP_MODIFIED and ALT_MODIFIED, 
the built-in GET_INFO (key_name, "key_modifiers") returns the integer 
12. 


EXAMPLE The first statement in the following code creates a VAXTPU key name 
for the key sequence produced by pressing the CTRL key, the SHIFT 
key, and the 4 key on the keypad, all at once. The new key name 
is assigned to the variable key_name. The second statement fetches 
the integer equivalent of this combination of key modifiers. The third 
statement displays the integer 3 in the message buffer. The IF clause 
of the fourth statement shows how to test whether a key name was 
created using a modifier. (Note, however, that this statement would 
not detect whether a key name was created using the keyword SHIFT_ 
KEY.) The THEN clause shows how to fetch the key modifier keyword or 
keywords used to create a key name. The final statement displays the 
string KEY_NAME (KP4, SHIFT_MODIFIED, ALT_MODIFIED) in the 
message buffer. 


néw_key := KEY_NAME (KP4, SHIFT MODIFIED, CTRL MODIFIED) ; 
modifier value >= GET INFO (new _ _key, “key_modifiers"); 


MESSAGE (STR (modifier value) ); 
IF GET INFO (new_key, “key modifiers") 
THEN 

the name := GET INFO (new key, "name") 
ENDIF; 
MESSAGE (STR (the name) ); 
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GET_ INFO (SCREEN, "active_area") 


Fetches information about the active area (the area in which VAXTPU ignores 
movements of the pointer cursor). 


For more information about the GET_INFO built-in, see the VAX Text 
Processing Utility Manual. 


FORMAT array a et i 
: inte i \rs GET INFO (SCREEN, "active_area") 


PARAMETERS SCREEN. 


A keyword indicating that GET_INFO is to fetch information about the 
VAXTPU screen. 


"active_area”’ 
A string requesting GET_INFO to return information on the location and 
dimensions of the application’s active area. 


return value 


array An array containing information on the location and dimensions of the 
active area. 
integer The value 0, returned if there is no active area. 


DESCRIPTION  GET_INFO (SCREEN, “active_area") returns an array containing 
information on the location and dimensions of the application’s active 
area. The active area is the region in a window in which VAXTPU ignores 
movements of the pointer cursor for purposes of distinguishing clicks 
from drags. When you press down a mouse button, VAXTPU interprets 
the event as a click if the upstroke occurs in the active area with the 
downstroke. If the upstroke occurs outside the active area, VAXTPU 
interprets the event as a drag operation. 


A VAXTPU layered application can have only one active area at a time, 
even if the application has more than one window visible on the screen. 
An active area is only valid if you are pressing a mouse button. The 
default active area occupies one character cell. By default, the active area 
is located on the character cell pointed to by the pointer cursor. 


For information on mouse button clicks, which are related to the concept 
of an active area, see the XUI Style Guide. 


GET_INFO (SCREEN, "active_area") returns five pieces of information 
about the active area in integer-indexed elements of the returned array. 
You need not use the CREATE_ARRAY built-in before using GET_INFO 
(SCREEN, "active_area"); VAXTPU assigns a properly structured array to 
the return variable you specify. The structure of the array is as follows: 
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Array 
Element 
array {1} 
array {2} 
array {3} 
array{4} 
array{5} 


GET_INFO (SCREEN, "active_area") 


Contents 


The window containing the active area 

The column forming the leftmost edge of the active area. 
The row forming the top edge of the active area. 

The width of the active area, expressed in columns. 

The height of the active area, expressed in rows. 
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GET_INFO (SCREEN, "event") 


If called from within a global selection grab or ungrab routine, identifies the 
global selection that was grabbed or lost. If called from within a routine that 
responds to requests for information about a global selection, returns the 
information an application needs to respond to the selection event. 


For more information about the GET_INFO built-in, see the VAX Text 
Processing Utility Manual. 


For more information about grabbing and ungrabbing a global selection, see 
the VMS DECwindows Guide to Application Programming. 


FORMAT integer 
PRIMARY 
SECONDARY ‘= GET_INFO 
selection name 
array 
(SCREEN, "event", 
GLOBAL_SELECT) 


PARAMETERS SCREEN 


A keyword used to preserve compatibility with future versions of VAXTPU. 


“event” 
A string indicating that GET_INFO is to supply information about a 
DECwindows event. 


GLOBAL_ SELECT 


A keyword indicating that GET_INFO is to supply information about a 
global selection. 


return value 


integer The integer 0, indicating that the built-in is not responding to 
a grab, an ungrab, or a selection information request. 

PRIMARY A keyword indicating that the global selection is the primary 
global selection. 

SECONDARY A keyword indicating that the global selection is the 


secondary global selection. 


selection_name A string naming the global selection that is the subject of 
the information request. This string is returned only if the 
selection is not the primary or secondary global selection. 
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array A two-element array that is returned if the built-in is used 
in a global selection read routine. The first of the array’s 
two elements contains a keyword or string identifying which 
of the global selections is the subject of an information 
request. The second element contains a string naming the 
global selection property (such as text or a line number) that 
is the subject of an information request. 


DESCRIPTION _s[f called from within a global selection grab or ungrab routine, GET_INFO 
(SCREEN, "event", GLOBAL_SELECT) identifies the global selection 
that was grabbed or lost. The built-in returns a keyword if the global 
selection was the primary or secondary selection. GET_INFO (SCREEN, 
"event", GLOBAL_SELECT) returns a string naming the global selection 
if the grab or ungrab involves a global selection other than the primary or 
secondary selection. 


If called from within a routine that responds to requests for information 
about a global selection, GET_INFO (SCREEN, "event", GLOBAL_ 
SELECT) returns an array. The array contains the information an 
application needs to respond to the selection event. The array contains 
the following information: 


e array {1}—The keyword PRIMARY, the keyword SECONDARY, or a 
string. This element identifies which global selection was read. 


e array {2}—A string. This element identifies the global selection 
property about which information has been requested. 


outside a global selection read, 
grab, or ungrab routine. 
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GET_INFO (SCREEN, "global select") 


Indicates whether VAXTPU currently owns the specified global selection. 


For more information about the GET_INFO built-in, see the VAX Text 
Processing Utility Manual. 


FORMAT integer := GET_INFO (SCREEN, "global_select", 
PRIMARY 
SECONDARY _ }) 
selection _name 


PARAMETERS SCREEN 


A keyword indicating that GET_INFO is to fetch ce eaeign about the 
VAXTPU screen. 


"“global_select" 


A string indicating that GET_INFO is to fetch information about a global 
selection. 


PRIMARY 


A keyword directing VAXTPU to get information on the primary global 
selection. 


SECONDARY 


A keyword directing VAXTPU to get information on the secondary global 
selection. 


selection_name 


A string identifying the global selection about which VAXTPU is to get 
information. 


return value Returns the integer 1 if VAXTPU currently owns the specified global 
selection; 0 if it does not. 
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GET_INFO (SCREEN, "grab_routine") 


Returns the application’s global selection or input focus grab routine. 


FORMAT integer 
program == GET_INFO (SCAEEN, 
learn_seq 
"grab_routine", 
GLOBAL_SELECT ) 
INPUT_FOCUS 


PARAMETERS SCREEN 


A keyword used to preserve compatibility with future versions of VAXTPU. 


"grab_routine" 
A string indicating that GET_INFO is to fetch the application’s grab 
routine. 


GLOBAL_SELECT 
A keyword indicating that GET_INFO is to fetch the global selection grab 
routine. 


INPUT FOCUS 
A keyword indicating that GET_ INFO i is to fetch the input focus grab 
routine. 


return value 


integer The integer 0, indicating the requested grab routine is not 
present. 
program The program designated as the application’s global 


selection or input focus grab routine. 


learn_seq The learn sequence designated as the application’s global 
selection or input focus grab routine. 
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GET_INFO (SCREEN, "icon_name") 


Returns the string used as the layered application’s name in the DECwindows 
icon box. 


FORMAT string :=GET_INFO (SCREEN, "icon_name") 


PARAMETERS SCREEN 
A keyword indicating that GET_INFO is to fetch information about the 
VAXTPU screen. 


"Icon_name" 
A string indicating that GET_INFO is to fetch the string used as the 
layered application’s name in the DECwindows icon box. 


return value The string used as the layered application’s name in the DECwindows icon 
box. 
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GET_INFO (SCREEN, "input_focus") 


Indicates whether VAXTPU currently owns the input focus. Input focus is the 
ability to process user input from the keyboard. 


For more information about the GET_INFO built-in, see the VAX Text 
Processing Utility Manual. 


FORMAT 


integer :=GET_INFO (SCREEN, "input_focus") 


PARAMETERS 


return value 


SCREEN 
A keyword indicating that GET_INFO is to fetch information about the 
VAXTPU screen. 


“input_focus" 
A string indicating that GET_INFO is to fetch information about the input 
focus. 


The integer 1 if VAXTPU owns the input focus, otherwise 0. 
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GET INFO (SCREEN, "length") © 


Returns the current length of the screen (in rows). 


For more information about the GET_INFO built-in, see the VAX Text 
Processing Utility Manual. 


FORMAT integer := GET_INFO (SCREEN, "length") 


PARAMETERS SCREEN | 
A keyword indicating that GET_INFO is to fetch information about the 
VAXTPU screen. | 


"length" 


A string indicating that GET_INFO is to fetch the current length of the 
VAXTPU screen. 


return value The current length of the VAXTPU screen, in rows. 


VMS DECwindows VAXTPU Built-In Procedures 
GET_INFO (SCREEN, "new_length") 


GET_INFO (SCREEN, "new length") 


Returns the length (in rows) that the screen will have after the resize action 
routine has been executed. 


For more information about the GET_INFO built-in, see the VAX Text 
Processing Utility Manual. 


FORMAT 


integer := GET_INFO (SCREEN, "new_length") 


PARAMETERS 


return value 


SCREEN 
A keyword indicating that GET_INFO is to fetch information about the 
VAXTPU screen. | 


“new_length" 
A string indicating that GET_INFO is to fetch the length (in rows) that 
the screen will have after the resize action routine has been executed. 


The length (in rows) that the screen will have after the resize action 
routine has been executed. 


DESCRIPTION 


Resize action routines should use the length returned by GET_INFO 
(SCREEN, "new_length") to determine the length of their windows. If 
used outside of a resize action routine, this length is the same as the 
current length of the screen. 
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GET INFO (SCREEN, "new width") 


Returns the width (in columns) the screen will have after the resize action 
routine has been executed. 


For more information about the GET_INFO built-in, see the VAX Text 
Processing Utility Manual. 


FORMAT integer := GET_INFO (SCREEN, "new_width") 


PARAMETERS SCREEN 
A keyword indicating that GET_INFO is to fetch information about the 
VAXTPU screen. 


“new_width” 
A string indicating that GET_INFO is to fetch the width (in columns) that 
the screen will have after the resize action routine has been executed. 


return value The width (in columns) that the screen will have after the resize action 
routine has been executed. 


DESCRIPTION _ Resize action routines should use the length returned by GET_INFO 
(SCREEN, "new_width") to determine the width of their windows. If used 
outside of a resize action routine, this width is the same as the current 
width of the screen. 
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GET_INFO (SCREEN, "old_length") 


Returns the length (in rows) of the screen before the most recent resize event. 


For more information about the GET_INFO built-in, see the VAX Text 
Processing Utility Manual. 


FORMAT integer :=GET_INFO (SCHREEN, "old_length") 


PARAMETERS SCREEN 
A keyword indicating that GET_INFO is to fetch information about the 
VAXTPU screen. 


"“old_length" 
A string indicating that GET_INFO is to fetch the length (in rows) that 
the screen had before the most recent resize event. 


return value The length (in rows) that the screen had before the most recent resize 
event. 


DESCRIPTION The old_length value is initially set to the length of the screen at startup. 
This value is reset after VAXTPU processes a resize event and before 
VAXTPU executes the resize action routine. 
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GET INFO (SCREEN, "old width") 


Returns the width (in columns) of the screen before the most recent resize 
event. 


For more information about the GET_INFO built-in, see the VAX Text 
Processing Utility Manual. 


FORMAT integer := GET_INFO (SCREEN, "old_width") 


PARAMETERS SCREEN 
A keyword indicating that GET_INFO is to fetch information about the 
VAXTPU screen. 


"old_width" 
A string indicating that GET_INFO is to fetch the width (in columns) that 
the screen had before the most recent resize event. 


return value The width (in columns) that the screen had before the most recent resize 
event. 


DESCRIPTION The old_width value is initially set to the width of the screen at startup. 
This value is reset after VAXTPU processes a resize event and before 
VAXTPU executes the resize action routine. 
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GET_INFO (SCREEN, "read_routine") 


Returns the global selection read routine. 


For more information about the GET_INFO built-in, see the VAX Text 
Processing Utility Manual. 


FORMAT integer | sities ) 
program == GET INFO /( 
learn sequence SCREEN 

"read_routine", 
GLOBAL_SELECT) 


PARAMETERS _ buffer 


The buffer with which the global selection read routine is to be associated. 


SCREEN 
A keyword directing VAXTPU to return the application’s defauil yiobai 
selection read routine. 


"read_routine" 


A string indicating that the built-in is to return a read routine. 


GLOBAL_SELECT 


A keyword indicating that the built-in is to return the global selection read 


routine. 
return value 
integer The value 0 if a global selection read routine has not been 
set for either the buffer or the application. 
program The program implementing the global selection read routine 
for either the buffer or the application. 
learn_sequence The learn sequence implementing the global selection read 


routine for either the buffer or the application. 


DESCRIPTION _ Returns the program or learn sequence that VAXTPU executes when it 
owns a global selection and another application has requested information 
about that selection. If the application has not specified a global selection 
read routine, 0 is returned. 


The first parameter indicates whether the application is asking for the 
buffer-specific read routine or the application’s default read routine. 
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GET INFO (SCREEN, "screen limits") 


Returns an integer-indexed array specifying the minimum and maximum 
screen length and width. 


For more information about the GET_INFO built-in, see the VAX Text 
Processing Utility Manual. 


FORMAT 


array :=GET_INFO SCAEEN, "screen_limits" 


PARAMETERS 


return value 


SCREEN 


A keyword indicating that GET_INFO is to fetch information about the 


VAXTPU screen. 


“screen_limits" 
A string indicating that GET_INFO is to fetch information about the 
minimum and maximum screen length and width. 


array 


An integer-indexed array using four elements to specify the minimum 
and maximum screen width and length. The array indices and their 
corresponding elements are as follows: 


1 


The minimum screen width, in columns. This value must be at least 
0 and less than or equal to the maximum screen width. The default 
value is 0. 

The minimum screen length, in lines. This value must be at least 0 
and less than or equal to the maximum screen length. The default 
value is 0. 

The maximum screen width, in columns. This value must be 
greater than or equal to the minimum screen width and less than or 
equal to 255. The default value is 255. 

The maximum screen length, in lines. This value must be greater 
than or equal to the minimum screen length and less than or equal 
to 255. The default value is 255. 
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GET INFO (SCREEN, “time") 


Returns the amount of time after requesting global selection information that 
VAXTPU waits for a reply. When the time has expired, VAXTPU assumes the 
request will not be answered. 


For more information about the GET_INFO built-in, see the VAX Text 
Processing Utility Manual. 


FORMAT string :=GET_INFO (SCAEEN, "time", 
GLOBAL_SELECT) 


PARAMETERS SCREEN 
A keyword indicating that GET_INFO is to fetch information about the 
VAXTPU screen. 


"t j m e ve 
A string indicating that GET_INFO is to fetch information about how long 
VAXTPU waits to receive information. 


GLOBAL_SELECT 
A keyword indicating that GET_INFO is to fetch the global selection 
ungrab routine. 


return value | 
string A string in VMS delta time format indicating how long VAXTPU waits. 
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GET_INFO (SCREEN, "ungrab_routine") 


Returns the application’s global selection or input focus ungrab routine. 


FORMAT int 
prog = GET_INFO 
learn 
(SCREEN, 


"ungrab_routine", 
GLOBAL_SELECT ) 
INPUT_FOCUS 


PARAMETERS SCREEN : 
A keyword used to preserve compatibility with future versions of VAXTPU. 


“ungrab_routine” 


A string indicating that GET_INFO is to fetch the application’s ungrab 
routine. 


GLOBAL SELECT 
A keyword indicating that GET_INFO is to fetch the global selection 
ungrab routine. 


INPUT FOCUS 
A keyword indicating that GET_INFO is to fetch the input focus ungrab 


routine. 
return value 
int The integer 0. This value indicates the requested ungrab routine is not 
present. 
prog The program designated as the application’s global selection or input 
focus ungrab routine. 
learn The learn sequence designated as the application’s global selection or 


input focus ungrab routine. 


DESCRIPTION _ Returns the program or learn sequence that VAXTPU executes when it 
loses ownership of a global selection or of the input focus. 
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GET_INFO (SYSTEM, "enable _ resize") 


Indicates whether resize operations are enabled. 


For more information about the GET_INFO built-in, see the VAX Text 
Processing Utility Manual. 


FORMAT integer :=GET_INFO (SYSTEM, "enable_resize") 


PARAMETERS SYSTEM 
A keyword indicating that GET_INFO is to fetch information about global 
settings in VAXTPU. 


"enable_resize" 
A string indicating that GET_INFO is to indicate whether resize 
operations are enabled. 


return vaiue The value 1 if resize operations are enabled, otherwise 0. By default, 
resize operations are not enabled. 
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GET_INFO (SYSTEM, "resize_action") 


Returns the current resize action routine. 


For more information about the GET_INFO built-in, see the VAX Text 
Processing Utility Manual. 


FORMAT integer 
| program ==GET_INFO (SYSTEM, 
learn_sequence 
"resize_action") 


PARAMETERS SYSTEM 
A keyword indicating that GET_INFO is to fetch information about global 
settings in VAXTPU. 


"resize_action" 
A string indicating that GET_INFO is to fetch the application’s resize 
action routine if it is present. 


return value 


integer The integer 0, indicating the requested resize action routine 
is not present. 

program The program designated as the application’s resize action 
routine. 

learn_sequence The learn sequence designated as the application’s resize 


action routine. 
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GET_INFO (WIDGET, "callback_parameters") 


Fetches the widget instance performing the callback, the closure value 
associated with the widget instance, and the reason for the callback. 


For more information about the GET_INFO built-in, see the VAX Text 
Processing Utility Manual. 


FORMAT integer :=GET_INFO (WIDGET, 
"callback_parameters", 
array) 

PARAMETERS WIDGET 


return value 


A keyword directing GET_INFO to fetch information about VAXTPU 
widgets in general or about a specific widget whose name you do not know 
at the time you use the built-in. 


"callback_parameters” 

A string directing GET_INFO to get information about the widget that is 
calling back, the reason for the callback, and the closure associated with 
the widget. 


array 


An array with the following indices: "widget", "closure", and "reason_ 
code". The built-in places the corresponding values in the array elements. 


integer The value 0 if the call was encountered outside a callback procedure, 
1 if the call was encountered within a callback procedure and callback 
information is available. 


DESCRIPTION 


VAXTPU automatically creates the array into which the return values are 
placed. 


Use this built-in only in a widget callback procedure. If you use this 
built-in outside a widget callback procedure, the value returned is 
indeterminate. 


For more information about callbacks and closure values in DECwindows 
VAXTPU, see Chapter 7. For general information about using callbacks 
and closure values, see the VMS DECwindows Guide to Application 
Programming. 
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EXAMPLE The following procedure shows one possible way that a layered 
application can use GET_INFO (WIDGET, "callback_parameters", 
array). The procedure is a simplified version of the EVE procedure 
eve$callback_dispatch. You can find the original version in 
SYS$EXAMPLES:EVE$MENUS.TPU. For more information about using 
the files in SYS$EXAMPLES as examples, see Section 7.7. 


This version of eve$callback_dispatch handles 

event callbacks from EVE widgets. The statement 

GET_INFO (WIDGET, "callback_parameters", temp_array) copies the 
following three items into elements of the array temp_array: 


e The widget that is calling back 
¢ The widget’s integer closure 


e The reason why the widget is calling back 


The array eve$$x_widget_array contains pointers to all of EVE’s callback 
routines in elements indexed by the appropriate integer closure values. 
This procedure locates the correct index in the array and executes the 
corresponding callback routine. | 


Warning: This simplified version of eve$callback_dispatch does not 
completely replace the version in existing EVE Version 2.2 code. 
Furthermore, DIGITAL does not guarantee that this example will 
work successfully with future versions of EVE. This example 
is presented solely to illustrate how EVE uses the built-in 
GET_INFO (WIDGET, "callback_parameters", array) in a callback 
handling procedure. 


PROCEDURE eveScallback dispatch 


LOCAL the program, 
status, 
temp array; 


ON ERROR 
[TPUS CONTROLC]: 
eveS$x_state_ array {eve$$k_ command line flag} := eveS$k_invoked_ by key; 
eveSlearn abort; 
ABORT; 
[OTHERWISE] : 
eveS$x_state_array {eve$$k_command_ line flag} 
ENDON_ERROR 


eveSk_ invoked by key; 


IF NOT eve$x_decwindows active 


THEN 
RETURN (FALSE) ; 
ENDIF; 
eve$$x_state_array {eve$$k_command_line flag} := eve$k_invoked_by menu; 
status. <= 


GET INFO (WIDGET, "callback parameters", temp array); ! This statement using 
! GET INFO (WIDGET) 
! returns the calling 
! widget, the reason 
! code, and the closure. 
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! The following statements make the contents of "temp array" 
! available to all the eveS$widget_ xxx procedures 


eveSx_widget := temp array {"widget"}; 

! This array element contains the widget 

! that called back. 
eveSx widget tag := temp array {"closure"}; 

! This array element contains the widget tag 

! that is assigned to the widget in the UIL file. 
eveSx_ widget reason := temp array {"reason_ code"}; 

! This array element contains callback reason code. 


! The next line gets the callback routine from the array indexed 
! by closure values. 


the program := eve$$x widget _array {eve$x widget tag}; 


IF the program <> 0 
THEN 

EXECUTE (the program) ; 
ENDIF; 


eve$$x_ state array {eve$$k command line flag} := eve$k_invoked_ by key; 
RETURN; 


ENDPROCEDUREHE; 
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GET_INFO (WIDGET) 


Fetches the widget instance corresponding to the specified widget name. 


For more information about the GET_INFO built-in, see the VAX Text 
Processing Utility Manual. | 


FORMAT widget := GET_INFO (WIDGET, "widget_id”, 
| parent_widget, 


SCREEN. widget_name 
) 


PARAMETERS WIDGET 
A keyword directing GET_INFO to fetch information about VAXTPU 
widgets in general or about a specific widget whose name you do not know 
at the time you use the built-in. 


“widget_id" 
A string directing GET_INFO to return the widget instance whose name 
matches the specified widget name. 


parent_widget 
The parent of the widget instance returned by the built-in. 


SCREEN 


A keyword indicating VAXTPU’s main window widget is the ancestor of 
the widget instance that you want the built-in to return. 


widget_name 

A string that is the fully qualified name of the widget you want the built- 
in to return. To specify this parameter correctly, start the string with the 
name of the widget’s parent. Use the same name you used to specify the 
parent_widget parameter. If you used the SCREEN parameter instead of 
the parent_widget parameter, start the string with the following widget 
name: 


tpuSmainwindow 


Next, specify the names of the ancestors, if any, that occur in the widget 
hierarchy between the parent and the widget itself. Start with the 
ancestor just below the parent and specify progressively more immediate 
ancestors. Finally, specify the name of the widget you want the built-in to 
return. Separate all widget names with periods. 


The fully qualified widget name is case-sensitive. 


return value | 
widget The widget instance whose name matches the specified widget name. 
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DESCRIPTION  GET_INFO (WIDGET, "widget_id") calls the X Toolkit routine NAME TO 
WIDGET. : 


For more information on DECwindows concepts such as parent widgets, 
ancestor widgets, and the distinction between widget classes and widget 
instances, see the VMS DECwindows Guide to Application Programming. 


EXAMPLE The following statement assigns to the variable the_text_widget the widget 
instance named by the string NEW_DIALOG.NEW_TEXT. The widget 
instance is the child of the widget instance assigned to the variable new_ 
dialog. 


the text _widget := GET INFO (WIDGET, "widget_id", new_dialog, 
"NEW DIALOG.NEW TEXT") ; 
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GET_INFO (widget_variable, "callback_routine") 


Fetches the callback routine for the specified widget. 


For more information about the GET_INFO built-in, see the VAX Text 
Processing Utility Manual. 


FORMAT program _ | | 
learn_sequence f ~~ GET_INFO 
(widget_variable, "callback_routine") 


PARAMETERS~  widget_variable 


The widget instance whose callback routine you want to fetch. 


"callback_routine" 
A string directing GET_INFO to fetch the specified widget’s callback 


routine. 
return value 
program The program designated as the application’s callback 
routine. 
learn_sequence The learn sequence designated as the application’s callback 
routine. 


DESCRIPTION _ Returns the VAXTPU program or learn sequence that VAXTPU should 
execute when a widget callback occurs for the specified widget instance. 
For more information about callbacks, see Chapter 6. 


EXAMPLE The following statement executes the callback routine for the widget 
eve$x_replace_dialog. Note that this statement is valid only after the 
Replace dialog box has been used at least once, because EVE does not 
create any dialog box until you have invoked it. 


EXECUTE (GET INFO (eve$x_ replace dialog, 
"callback routine") ); 
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GET_INFO (widget_variable, "name") 


Returns the name of the specified widget instance. 


For more information about the GET_INFO built-in, see the VAX Text 
Processing Utility Manual. 


FORMAT string :=GET_INFO (widget_variable, "name") 


PARAMETERS'~ widget_variable 


The widget instance whose name you want to fetch. 


“name” 
A string directing GET_INFO to fetch the specified widget’s name. 


return value 
string The name of the specified widget instance. 


EXAMPLE The following procedure displays the name of the widget instance specified 
by the variable eve$x_replace_dialog. To confirm that the widget has been 
created as expected, the procedure also displays a message identifying the 
data type of the variable’s contents. Note that the procedure is valid only 
after the Replace dialog box has been used at least once, because EVE does 
not create any dialog box until you have invoked it. 


A statement containing the built-in GET_INFO (widget, "name") can 
be useful in code implementing a debugging command that evaluates 
VAXTPU statements, expressions, and variables. 

PROCEDURE sample return_name 

LOCAL status; 


status := GET INFO (eveSx replace dialog, 
"name") : 

MESSAGE ("The data type of status is: "); 

MESSAGE (STR (GET _INFO(status, "type"))); 


( 
( 
MESSAGE ("The value of status is: "); 
MESSAGE (STR (status) ); 


ENDPROCEDURE; 
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GET_INFO (widget_variable, "widget_info") 


Provides the current values for one or more resources of the specified widget. 


For more information about the GET_INFO built-in, see the VAX Text 
Processing Utility Manual. 


FORMAT status := GET INFO (widget_variable, "widget_info" 
array 
arg _pairf[, arg_pair... ] 


PARAMETERS'~ widget_variable 


The widget instance whose resource values you want to fetch. 


"widget_info" 
A string directing GET_INFO to fetch the widget’s specified resource 
values. 


array 

An array specifying the resources whose values are to be fetched. Each 
array index must be a string naming a valid resource for the specified 
widget. Note that resource names are case sensitive. The corresponding 
array element contains the value of the resource. The array can contain 
any number of elements. | 


arg_pair 
A string naming a valid resource for the widget followed by a variable to 
store the value of the resource. Use the following format: 


resource name string, resource value 


You can fetch as many resources as you want by using multiple pairs of 
arguments. 


return value 
status An integer representing the status with which the built-in completed 
execution. You need not use the return variable in a statement that 
includes this built-in. 


DESCRIPTION This built-in is functionally equivalent to the XUI Toolkit routine GET 
VALUES. 


If you specify the name of a resource that the widget does not support, 
VAXTPU signals the error TPU$_ARGMISMATCH. 


For more information about specifying resources, see Chapter 6. 
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EXAMPLE The following procedure, user_widget_replace_all, shows one possible 
way that a layered application can use GET_INFO (widget, "widget_ 
info"). The procedure is a modified version of the EVE procedure 
eve$$widget_replace_all. You can find the original version in 
SYS$EXAMPLES:EVE$MENUS.TPU. For more information about using 
the files in SYS$EXAMPLES as examples, see Section 7.7. 


Procedure user_widget_replace_all determines what user message to 
display in response to the EVE command REPLACE. The procedure uses 
GET_INFO (widget, "widget_info") to fetch the value of the resource 
dwt$c_nvalue. This resource represents whether the Replace All toggle 
button appears unshaded, in which case the resource’s value is 0, or 
appears solid, in which case the value is 1. 


PROCEDURE user _widget_replace all 


CONSTANT 
user k widget_name := "REPLACE DIALOG.REPLACE ALL"; 


LOCAL the value, 
parent widget, 
replace all button; 


parent widget := eve$x replace dialog; 


replace_all_ button := GET_INFO (WIDGET, “"widget_id", 
parent widget, 
user_k widget_name) ; 


GET _ INFO (replace _all button, ! This statement uses 
"widget_info", eveSdwtSc_nvalue, ! GET INFO (widget, "“widget_info") 
the value); Isto -feteh ‘the value: of the 


! dwtSc_ nvalue resource. 


Lif the. value 


THEN 

MESSGE ("All instances will be replaced."); 
ELSE 

MESSGE ("Not all instances will be replaced."); 
ENDIF; 
ENDPROCEDURE; 
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GET_INFO (widget variable, "text") 


Fetches the string that is the value of the specified simple text widget. (The 
value of a text widget is the text entered into the text widget by the user in 
response to a prompt in a dialog box.) 


For more information about the GET_INFO built-in, see the VAX Text 
Processing Utility Manual. 


FORMAT string :=GET_INFO (widget_variable, "text") 


PARAMETERS. variable 


The widget instance whose text you want to fetch. 


“text” 
A string directing GET_INFO to fetch the specified widget’s text value. 


return value 
string The text value of the specified widget instance. 


DESCRIPTION This built-in is eqivalent to the XUI Toolkit routine dwt$s_text_get_string. 
If the specified widget is not of class SText, VAXTPU signals the status 
TPU$_WIDMISMATCH. 


EXAMPLE The following code fragment creates an EVE file name dialog box widget 
and assigns the widget to the variable eve$x_needfilename_dialog. Next, 
the fragment assigns to the variable the_value a string prompting you 
for the name of a file to which the buffer’s contents should be written. 
The fragment uses the built-in GET_INFO (WIDGET, "widget_id") to 
assign the dialog box’s label widget to the variable child_of_box. Finally, 
the fragment assigns to the label widget’s eve$dwt$c_nlabel resource the 
string contained in the_value. 


eve$x_needfilename_ dialog := create widget ("NEEDFILENAME DIALOG", 
eveSk_ widget_hierarchy, 
SCREEN, 
eveSkt_callback routine) ; 


the_value := message text ("Type filename for writing buffer ", 0, 
get_info (the buffer, "name")); 


child of box := get_info (WIDGET, "widget id", 
eve$Sx needfilename_ dialog, 
"NEEDFILENAME DIALOG.NEEDFILENAME LABEL") ; 


status := set (WIDGET, child _ of box, eve$dwt$c_nlabel, the value); 
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GET_INFO (window variable, "scroll bar’) 


Fetches the specified scroll bar widget if it exists, otherwise returns 0. 


For more information about the GET_INFO built-in, see the VAX Text 
Processing Utility Manual. 


FORMAT pero } = GET INFO  (window_variable, 
widget 
"scroll_bar'", 
{ HORIZONTAL 


VERTICAL 


PARAMETERS ' window_variable 
The window whose scroll bar you want VAXTPU to fetch. 


“scroll_ bar" 
A string directing VAXTPU to fetch a scroil bar in a VAXTPU window. 


HORIZONTAL 
A keyword directing VAXTPU to fetch the window’s horizontal scroll bar. 


VERTICAL 
A keyword directing VAXTPU to fetch the window’s vertical scroll bar. 


return value 
integer The value 0 if the window does not have the requested scroll bar. 


widget The widget instance implementing the vertical or horizontal scroll bar 
associated with a window. 


EXAMPLE The following statement returns the vertical scroll bar widget associated 
with the current window: 


the bar := GET INFO (CURRENT WINDOW, “scroll bar", VERTICAL) ; 


For another example of code using GET_INFO (window_variable, "scroll_ 
bar") see Example 7-6. 
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GET_INFO (window_variable, "scroll_bar_auto_thumb") 


Indicates whether automatic adjustment of the specified scroll bar slider is 
enabled. 


For more information about the GET_INFO built-in, see the VAX Text 
Processing Utility Manual. 


FORMAT oe } = GET INFO (window_variable, 
widget 


"scroll_bar_auto_thumb", 
oe } ) 
VERTICAL 


PARAMETERS window_variable 


The window whose scroll bar slider is the subject of the information 
request. 


“scroll_bar_auto_thumb” 


. 


A string directing GET_INFO to indicate whether automatic adjustment of | 


the scroll bar slider is enabled. 


HORIZONTAL 


A keyword specifying the horizontal scroll bar. 


VERTICAL 
A keyword specifying the vertical scroll bar. 


return value 
integer The value 1 if automatic adjustment is enabled, 0 if it is disabled. 


EXAMPLE The following statement returns an integer indicating whether automatic 
adjustment is enabled for the vertical scroll bar slider associated with the 
current window. 


status := GET INFO (CURRENT WINDOW, 
"scroll bar auto thumb", VERTICAL) ; 


For another example of code using GET_INFO (window_variable, "scroll_ 
bar_auto_thumb", WINDOW) see Example 7-6. 
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Returns a VAXTPU keyword for a key or a combination of keys, or creates 

a keyword used as a key name by VAXTPU. In this version, KEY_NAME 
accepts new keywords for the optional parameter that specifies key modifiers 
(such as the CTRL key in the sequence CTRL/F12). The KEY_NAME built-in 
still performs all the functions that it performed in the version of VAXTPU 
released with VMS Version 5.0. 


For more information about the KEY_NAME built-in, see the VAX Text 
Processing Utility Manual. 


FORMAT 


keyword2 := KEY_NAME 

integer 

(< key_name 
string 
, SHIFT _KEY 
_ SHIFT MODIFIED | 

[<} , ALT MODIFIED f.-- JJ] 
CTRL MODIFIED | 
_ HELP_ MODIFIED 


, FUNCTION ) 
, KEYPAD 


PARAMETERS 


integer 

An integer that is either the integer representation of a keyword for a key, 
or is a value between 0 and 255 that VAXTPU interprets as a value of a 
character in the DEC Multinational Character Set. 


key name 
A keyword that is the VAXTPU name for a key. 


string 
A string that is the value of a key from the main keyboard. 


SHIFT_KEY 


A keyword specifying that the key name created includes one or more 
shift keys. The keyword SHIFT_KEY specifies the VAXTPU shift key, not 


the key on the keyboard marked “Shift.” The shift key is also referred to 


as the GOLD key in EVE. (See the description of the SET (SHIFT_KEY) 
built-in in the VAX Text Processing Utility Manual.) 


SHIFT_MODIFIED 


A keyword specifying that the key name created by the built-in includes 
the key marked SHIFT on the keyboard. The keyword SHIFT_MODIFIED 
specifies the key that toggles between uppercase and lowercase; not the 
key known as the GOLD key. 
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-KEY_NAME 


return value 


SHIFT_MODIFIED only modifies function keys and keypad keys. 
ALT_MODIFIED 


A keyword specifying that the key name created by the built-in includes 
the ALT key. Note that on most DIGITAL keyboards the ALT key is 
labeled COMPOSE CHARACTER. 


ALT_MODIFIED only modifies function keys and keypad keys. 
CTRL_MODIFIED 


A keyword specifying that the key name created by the built-in includes 
the CTRL key. 


CTRL_MODIFIED only modifies function keys and keypad keys. 
HELP MODIFIED 


A keyword specifying that the key name created by the built-in includes 
the HELP key. 


HELP_MODIFIED only modifies function keys and keypad keys. 


FUNCTION 


A parameter that specifies that the resulting key name is to be that of a 
function key. 


KEYPAD 


A parameter that specifies that the resulting key name is to be that of a 
keypad key. 


A VAXTPU keyword to be used as the name of a key. 


DESCRIPTION 


Using the KEY_NAME built-in, you can create key names that are 


modified by more than one key. For example, it is possible to create a 


name for a key sequence consisting of the GOLD key, the CTRL key, and 
an alphanumeric or keypad key. 


The built-in GET_INFO (key_name, "key_modifiers") returns a bit- 
encoded integer whose value represents the key modifier or combination 
of key modifiers used to create a given key name. For more information 
about interpreting the integer returned, see the description of GET_INFO 
(key_name, "key_modifiers"). 


The built-in GET_INFO (keyword, "name") has been extended to return a 
string including all the key modifier keywords used to create a key name. 
For more information about fetching the string equivalent of a key name, 
see the description of GET_INFO (keyword, "name"). 


SIGNALED 
ERRORS 
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TPU$_MUSTBEONE WARNING _ String must be one character long. 
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KEY NAME 
TPU$_NOTDEFINABLE WARNING — Second argument is not a valid 
reference to a key. 
TPU$_NEEDTOASSIGN ERROR Built-in call must be on the right- 
hand side of an assignment 
statement. 
TPU$_ARGMISMATCH ERROR Wrong type of data sent to the 
built-in. 
TPU$_BADKEY ERROR KEY_NAME accepts SHIFT_KEY, 


FUNCTION, or KEYPAD as a 
keyword argument. 


TPU$_TOOFEW ERROR Too few arguments passed to the 
KEY_NAME built-in. 
TPU$_TOOMANY ERROR Too many arguments passed to 


the KEY_NAME built-in. 


The following statements create a name for the key sequence 
GOLD/CTRL/KP4 and bind the EVE command FILL to the resulting 
key sequence: 


EXAMPLE 


new_key := KEY NAME (KP4, CTRL MODIFIED, DRLET: KEY):5 
DEFINE KEY ("eve fill", new_key); 
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MANAGE WIDGET 


Makes the specified widget instance visible, provided that the specified 
widget’s parent is also visible. 


FORMAT MANAGE WIDGET (wget[, widget... J) 


PARAMETERS’ widget 


The widget instance to be managed. 


DESCRIPTION This built-in performs the same functions as the XUI Toolkit MANAGE 
CHILD and MANAGE CHILDREN routines. 


If you have multiple children of a single widget that you want to manage, 
include them in a single call to MANAGE_WIDGET. Managing several 
widgets at once is more efficient than managing one widget at a time. 


All widgets passed in the same MANAGE_WIDGET operation must have 
the same parent. 


SIGNALED TPU$_INVPARAM ERROR Ye ified ter of th 
a Ou specified a parameter of the 
ERRORS wrong type. 
TPU$_TOOFEW ERROR Too few arguments passed to the 
built-in. 
TPU$_NORETURNVALUE ERROR The built-in cannot return a value. 
TPU$_REQSDECW ERROR You can use the built-in only if the 
DECwindows screen updater is in 
use. 
TPU$_WIDMISMATCH ERROR You have specified a widget whose 
class is not supported. 
EXAMPLE For a sample procedure using the MANAGE_WIDGET built-in, see 


Example 7-2. 
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READ CLIPBOARD 


Reads STRING format data from the clipboard and copies it into the current 
buffer, at the editing point, using the buffer’s current text mode (INSERT or 


OVERSTRIKE). 
FORMAT | range | := READ_CLIPBOARD 
UNSPECIFIED || "— 
return value 
range A range containing the text copied into the current buffer. 
unspecified A data type indicating that no data was obtained from the 


clipboard. 


DESCRIPTION _ If VAXTPU finds a line-feed character in the data, it removes the line feed 
and any adjacent carriage returns and puts the data after the line feed on 
the next line of the buffer. If VAXTPU must truncate the data from the 
clipboard, VAXTPU copies the truncated text into the current buffer. 


All text read from the clipboard is copied into the buffer starting at the 
editing point. If VAXTPU must start a new line to fit all the text into the 
buffer, the new line starts at column 1, even if the current left margin is 
not set at column 1. 


SIGNALED TPU$_CLIPBOARDLOCKED WARNING ~~ VAXTPU t read from th 
= cannot read from the 
ERRORS clipboard because some other 


application has locked it. 


TPU$_CLIPBOARDNODATA WARNING _ There is no STRING format data 
in the clipboard. 


TPU$_CLIPBOARDFAIL WARNING _ The clipboard has not returned 
any data. 


TPU$_REQSDECW ERROR You can use the built-in only if the 
DECwindows screen updater is in 
use. 

TPU$_STRTOOLARGE ERROR The amount of data in the 
clipboard exceeds 65,535 
characters. 


TPU$_TOOMANY ERROR Too many arguments passed to 
the built-in. 
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READ CLIPBOARD 


EXAMPLE 


The following procedure shows one possible way that an application 

can use the READ_CLIPBOARD built-in. This procedure is a modified 
version of the EVE procedure eve$$insert_clipboard. You can find the 
original version in SYS$EXAMPLES:EVE$DECWINDOWS.TPU. For more 
information about using the files in SYS$SEXAMPLES as examples, see 
Section 7.7. 


Procedure eve$$insert_clipboard fetches the contents of the clipboard and 
places them in the current buffer. 


PROCEDURE eve$Sinsert clipboard 


ON ERROR 


[TPUS_CLIPBOARDNODATA] : 
eveSmessage (EVES NOINSUSESEL) ; 
eveS$learn_abort; 
RETURN (FALSE) ; 
[TPUS_CLIPBOARDLOCKED] : 
eveSmessage (EVES CLIPBDREADLOCK) ; 
eveSlearn_abort; 
RETURN (FALSE) ; 


[TPUS TRUNCATE]: 


[OTHERWISE] : 


eveSlearn_abort; 


ENDON_ERROR; 


IF eveStest_if_ modifiable (CURRENT BUFFER) 


THEN 
READ CLIPBOARD; 


RETURN (TRUE) ; 
ENDIF; 


eve$learn abort; 
RETURN (FALSE) ; 


ENDPROCEDURE; 
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READ CLIPBOARD reads 
data from the clipboard 
and copies it into the 
current buffer. 
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READ GLOBAL SELECT 


Requests information about the specified global selection from the owner of 
the global selection. If the owner provides the information, READ GLOBAL _ 
SELECT reads it and copies it into the current buffer at the editing point, using 
the buffer’s current text mode (INSERT or OVERSTRIKE). The built-in also 
puts line breaks in the text copied into the buffer. 


FORMAT 1 | — :=] READ_GLOBAL_SELECT 


PRIMARY 
(i SECONDARY _ }, selection_property_name ) 
selection_name 


PARAMETERS PRIMARY 


A keyword indicating that the layered application is requesting 
information about a property of the primary global selection. 


SECONDARY 


A keyword indicating that the layered application is requesting 
information about a property of the secondary global selection. 


selection_name 

A string identifying the global selection whose property is the subject of 
the layered application’s information request. Specify the selection name 
as a string if the layered application needs information about a selection 
other than the primary or secondary global selection. 


selection_property_name 
A string specifying the property whose value the layered application is 


requesting. 
return value 
unspecified A data type indicating that the information requested by the 
layered application was not available. 
range A range containing the text copied into the current buffer. 


DESCRIPTION Use READ_GLOBAL_SELECT to ask the application that owns the 
specified global selection for information about a property of the global 
selection. For example, you can ask about the global selection’s font, the 
number of lines it contains, or the string-formatted data it contains, if any. 


All text read from the global selection is copied into the current buffer 
starting at the editing point. If VAXTPU must start a new line to fit all 
the text into the buffer, the new line starts at column 1, even if the current 
left margin is not set at column 1. 
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If the global selection information requested is an integer, the built-in 
converts the integer into a string before copying it into the current buffer. 
If the information requested is a string, the built-in copies the string into 
the buffer, replacing any line feeds with line breaks. Carriage returns 
adjacent to line feeds are not copied into the buffer. 


SIGNALED TPU$_BADKEY WARNING Y ecified an invalid keyword 
a ou specified an invali w 
ERRORS as a parameter. 

TPU$_GBLSELOWNER WARNING ~~ VAXTPU owns the global 
selection. 

TPU$_INVGBLSELDATA WARNING _ The global selection owner 
provided data that VAXTPU cannot 
process. 

TPU$_NOGBLSELDATA WARNING _ The global selection owner has 
indicated that it cannot provide the 
information requested. 

TPU$_NOGBLSELOWNER WARNING = You have requested information 
about an unowned global 
selection. 

TPU$_TIMEOUT WARNING _ The global selection owner did not 
respond before the timeout period 
expired. 

TPU$_ARGMISMATCH ERROR Wrong type of data sent to the 
built-in. 


TPU$_REQSDECW ERROR You can use the built-in only if the 
DECwindows screen updater is in 
use. | 


TPU$_TOOFEW ERROR Too few arguments passed to the 
built-in. 


TPU$_TOOMANY ERROR Too many arguments passed to 
the built-in. 


EXAMPLE The following statement reads the string-formatted contents of the primary 
global selection and copies it into the current buffer at the current location. 


READ GLOBAL SELECTION (PRIMARY, "STRING"); 


For another example of code using the READ_GLOBAL_SELECT built-in, 
see Example 7-9. 
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SET (ACTIVE AREA) 


Designates the specified area as the active area in a VAXTPU window. An 
active area is an area within which VAXTPU ignores movements of the pointer 
cursor. 


FORMAT 


SET (ACTIVE_AREA, window, column, row J, width, 
height }}) 


PARAMETERS 


ACTIVE_AREA 


A keyword directing VAXTPU to set an attribute of the active area. 


window 
The window in which you want to define the active region. 


column 


An integer specifying the leftmost column of the active region. 


row 
An integer specifying the topmost row of the active region. If you use 0, 
the active row is the status line. 


width 


An integer specifying the width in columns of the active region. Defaults 
to 1. 


height 
An integer specifying the height in rows of the active region. Defaults 
to 1. 


DESCRIPTION 


The active area is the region in a window in which VAXTPU ignores 
movements of the pointer cursor for purposes of distinguishing clicks 
from drags. When you press down a mouse button, VAXTPU interprets 
the event as a click if the upstroke occurs in the active area with the 
downstroke. If the upstroke occurs outside the active area, VAXTPU 
interprets the event as a drag operation. 


A VAXTPU layered application can have only one active area at a time, 
even if the application has more than one window visible on the screen. 
An active area is only valid if you are pressing a mouse button. The 
default active area occupies one character cell. By default, the active area 
is located on the character cell pointed to by the pointer cursor. 


For information on mouse button clicks, which are related to the concept 
of an active area, see the XUI Style Guide. 
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Table 5-1 lists the keywords for referring to click and drag operations. 


Table 5-1 VAXTPU Keywords Representing Mouse Events 


M1UP M2UP M3UP M4UP M5UP 
M1DOWN M2DOWN M3DOWN M4DOWN M5DOWN 
M1DRAG M2DRAG M3DRAG M4DRAG M5DRAG 
M1CLICK M2CLICK M3CLICK M4CLICK M5CLICK 
M1iCLICK2 M2CLICK2 M3CLICK2 M4CLICK2 M5CLICK2 
M1CLICK3 M2CLICK3 M3CLICK3 M4CLICK3 M5CLICK3 
M1iCLICK4 M2CLICK4 M3CLICK4 M4CLICK4 M5CLICK4 
M1CLICK5 M2CLICK5 M3CLICK5 M4CLICK5 M5CLICK5 
SIGNALED TPU$_BADVALUE ERROR An int t 
fd n integer parameter was 
ERRORS specified with a value outside 
the valid range. 
TPU$_EXTRANEOUSARGS ERROR One or more extraneous 
arguments have been specified 
for a DECwindows built-in. 
TPU$_INVPARAM ERROR One of the parameters was 
specified with data of the wrong 
type. 
TPU$_NORETURNVALUE ERROR The built-in cannot return a value. 
TPU$_REQSDECW ERROR You can use the built-in only if the 
DECwindows screen updater is in 
use. 
TPU$_TOOFEW ERROR Too few arguments passed to the 
built-in. 
TPU$_TOOMANY ERROR Too many arguments passed to 
the built-in. 
EXAMPLE The following procedure shows one possible way that an application 


can use SET (ACTIVE_AREA). The procedure is a modified version of 
the EVE procedure eve$$midown. You can find the original version in 
SYS$EXAMPLES:EVE$MOUSE.TPU. For more information about using 
the files in SYS$EXAMPLES as examples, see Section 7.7. 


Procedure eve$$m1down, when bound to MIDOWN, sets an active area 
when you press MB1. 


PROCEDURE eveSSmldown 


LOCAL the window, 
the column, 
the row, 


the width; 
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ON ERROR 
[OTHERWISE] : 
ENDON_ERROR; 


eveS$x_ pre mbl mark := MARK (FREE CURSOR); 
IF LOCATE MOUSE (the window, the column, the_row) 


THEN 
eveSx mbl_ in progress := 1; 
IF the row = 0 
THEN 
IF eveScurrent_indicator (the window, 
the column, 
the width) <> 0 
THEN 
IF eveSx_decwindows_active 
THEN 
SET (ACTIVE AREA, ! This statement sets 
the window, the_column, ! the active area. 
0, the width, 1); 
ENDIF; 
ELSE 
RETURN (FALSE) ; 
ENDIF; 
ELSE 
IF the window = eve$choice_ window 
THEN 
TF eveSScurrent choice (the column, eveSSx chosen range) 
THEN 7 7 
IF eve$x_decwindows_ active 
THEN 
SET (ACTIVE AREA, the window, the column, the_row, 
eve$$x_ choices column width, 1); 
ENDIF; 
ENDIF; 
else 
POSITION (MOUSE) ; 
eveS$x_mbl_ down free := MARK (FREE CURSOR); 
POSITION (TEXT) ; 
eveSclear_ select_position; 
eveSclear message; 
eve$$x_mb1_down_bound := MARK (NONE); 
POSITION (eve$$x_mbl_ down_free); 
ENDIF; 
ENDIF; 
RETURN (TRUE) ; 
ELSE 
RETURN (FALSE) ; 
ENDIF; 
ENDPROCEDURE; 
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SET (DRM HIERARCHY) 


Sets the User Interface Definition (UID) file or files to be used with VAXTPU. 


FORMAT integer := SET (DRM_HIERARCHY), 
filespec 
I, filespec ... ] 


PARAMETERS _filespec | 
A string specifying the UID file to be used. VAXTPU applies the VMS 
default file specification "SYS$LIBRARY: .UID" to the string you pass to 
SET (DRM_HIERARCHY). You must specify at least one file name. 


return value An integer that is the identification number for the XUI Resource Manager 
hierarchy. 


DESCRIPTION _ Using UID files to specify hierarchies makes it easy to translate the 
product into other languages and to modify an application’s interface 
without recompiling all the code implementing the application. 


For more information about UID files, see the VMS DECwindows Guide to 
Application Programming. 


parameter is not supported by the 
built-in. 

TPU$_TOOFEW ERROR Too few arguments passed to the 
built-in. 

TPU$_TOOMANY ERROR Too many arguments passed to 
the built-in. 


EXAMPLE The following statement designates the User Interface Definition (UID) 
3 file MYNODE$DUAO:[SMITH]EXAMPLE.UID as a file to be used with 
VAXTPU to create widgets needed by the layered application: 


example hierarchy := SET (DRM HIERARCHY, "“mynodeSdua0: [smith]example.uid") ; 


For examples of how the SET (DRM_HIERARCHY) built-in is used in 
procedures, see Example 7-1 and Example 7—2. 
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SET (ENABLE RESIZE) 


Enables or disables resizing of the VAXTPU screen. 


FORMAT ON 
SET (ENABLE_RESIZE, i \) 


PARAMETERS ENABLE RESIZE 
A keyword directing VAXTPU to enable or disable screen resizing. 


ON 


A keyword enabling screen resizing. 


OFF 


A keyword disabling screen resizing. 


DESCRIPTION _ If you specify the ON keyword, VAXTPU gives the DECwindows window 
manager hints (parameters that the window manager is free to use or 
ignore) on the allowable maximum and minimum sizes for the VAXTPU 
screen. The hints are set by the SET (SCREEN_LIMITS, array) built-in. 
If you specify the OFF keyword, VAXTPU uses the screen’s current width 
and length as the maximum and minimum size. 


SIGNALED TPU$_BADKEY WARNING ¥ ified an invalid k d 
* ou specified an invalid keywor 
ERRORS as a parameter. 
TPU$_INVPARAM ERROR One of the parameters was 
specified with data of the wrong 
type. 
~TPU$_NORETURNVALUE ERROR The built-in cannot return a value. 
TPU$_REQSDECW ERROR You can use the built-in only if the 
DECwindows screen updater is in 
use. 
TPU$_TOOFEW ERROR Too few arguments passed to the 
built-in. 
TPU$_TOOMANY ERROR Too many arguments passed to 
the built-in. 
EXAMPLE The following statement enables screen resizing: 


SET (ENABLE RESIZE, ON); 


To see this statement used in an initializing procedure, see the example in 
the description of the SET (SCREEN_LIMITS) built-in. 
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SET (GLOBAL SELECT) — 


Requests ownership of the specified global selection property. 


FORMAT [integer :=] SET (GLOBAL_SELECT, SCREEN, 
PRIMARY 

SECONDARY | }) 
selection _name 


PARAMETERS GLOBAL SELECT 
A keyword indicating that GET_INFO is to fetch the global selection 
ungrab routine. 


PRIMARY 


A keyword directing VAXTPU to request ownership of the primary global 
selection. 


SECONDARY 


A keyword directing VAXTPU to request ownership of the secondary global | 


selection. 


selection_name 
A string naming the global selection whose ownership VAXTPU is to 
request. 


return value The value 1 if the global selection ownership request was granted; 0 
otherwise. 


DESCRIPTION The built-in returns the integer 1 if the request for ownership of a global 
selection was granted; otherwise 0. 


The last parameter identifies the global selection of which VAXTPU is to 
grab ownership. 


VAXTPU knows immediately if its request is granted. Therefore, VAXTPU 
does not automatically execute the global selection grab routine when 

it encounters this built-in. VAXTPU executes the routine only when it 
automatically grabs the primary selection. 


For more information about the concept of global selection, see the XUI 
Style Guide. 


Wao OS 
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SIGNALED TPU$_BADKEY WARNING Y ified an invalid k d 
a ou specified an invalid keywor 
ERRORS as a parameter. 
TPU$_INVPARAM ERROR One of the parameters was 
specified with data of the wrong 
type. 
TPU$_REQSDECW ERROR You can use the built-in only if the 
DECwindows screen updater is in 
use. 
TPU$_TOOFEW ERROR Too few arguments passed to the 
built-in. 
TPU$_TOOMANY ERROR Too many arguments passed to 
the built-in. 
EXAMPLE The following statement requests ownership of the primary global 
selection. 


SET (GLOBAL SELECT, SCREEN, PRIMARY) ; 


For another example of code using the SET (GLOBAL_SELECT) built-in, 
see Example 7-10. 
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SET (GLOBAL SELECT GRAB) 


Specifies the program or learn sequence VAXTPU should execute whenever it 
automatically grabs ownership of the primary selection. 


FORMAT SET (GLOBAL_SELECT_GRAB, SCREEN 
, buffer 
, learn_sequence 
, program 
E , range D 
, string 
, NONE 


PARAMETERS buffer 


The buffer that contains the grab routine. If you do not specify this 
parameter, the current global selection grab routine is deleted and your 


application is not informed when VAXTPU grabs the global primary global | 


selection. 


learn_sequence 

The learn sequence specifying the grab routine. If you do not specify this 
parameter, the current global selection grab routine is deleted and your 
application is not informed when VAXTPU grabs the global primary global 
selection. 


program 
The program specifying the grab routine. If you do not specify this 
parameter, the current global selection grab routine is deleted and your 


application is not informed when VAXTPU grabs the global primary global | 


selection. 


range 

The range that contains the grab routine. If you do not specify this 
parameter, the current global selection grab routine is deleted and your 
application is not informed when VAXTPU grabs the global primary global 
selection. 


string 

The string that contains the grab routine. If you do not specify this 
parameter, the current global selection grab routine is deleted and your 
application is not informed when VAXTPU grabs the global primary global 
selection. 


NONE 


A keyword directing VAXTPU to delete the current global selection grab 
routine. | 
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SIGNALED TPU$_BADKEY WARNING Y ified an invalid k d 
e ou specified an invalid keywor 
ERRORS as a parameter. 
TPU$_INVPARAM ERROR One of the parameters was 
specified with data of the wrong 
type. 
TPU$_NORETURNVALUE ERROR The built-in cannot return a value. 
TPU$_REQSDECW ERROR You can use the built-in only if the 
DECwindows screen updater is in 
use. 
TPU$_TOOFEW ERROR Too few arguments passed to the 
built-in. 
TPU$_TOOMANY ERROR Too many arguments passed to 
the built-in. 


DESCRIPTION For more information about VAXTPU’s global selection support, see 
Section 7.2. 


EXAMPLE The following statement designates the procedure user_grab_global as a 
global selection read routine: 


SET (GLOBAL SELECT GRAB, SCREEN, "user grab global"); 


For another example of code using the SET (GLOBAL_SELECT_GRAB) 


built-in, see Example 5-1. 


Sample Code Setting Various Global Selection and Input Focus Routines 


Example 5—1 shows possible ways that a layered application can use 
statements setting global selection and input focus routines. The example 
contains portions of the procedure eve$mouse_module_init. You can find 
the original version in SYS$EXAMPLES:EVE$MOUSE.TPU. For more 
information about using the files in SYS$EXAMPLES as examples, see 
Section 7.7. 


The statements in Example 5-1 designate EVE’s global selection read 
routine, global selection ungrab routine, global selection grab routine, 
input focus grab routine, and input focus ungrab routine. 
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Example 5-1 Initialization Procedure Using Variants of the SET Built-In 


PROCEDURE eveSmouse module init 


e 
e 
° 


IF GET INFO (SCREEN, "decwindows") 
THEN 


SET (GLOBAL SELECT READ, SCREEN, “eve$write global select"); 

SET (GLOBAL SELECT UNGRAB, SCREEN, "eveSglobal_select_ungrab") ; 

SET (GLOBAL SELECT GRAB, SCREEN, "“eveS$global_ select _grab"); 

SET (INPUT FOCUS GRAB, SCREEN, "“eveSinput_focus_grab") ; 

SET (INPUT FOCUS UNGRAB, SCREEN, “eveSinput_focus_ungrab") ; 
ENDIF; 


ENDPROCEDURE; 
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SET (GLOBAL SELECT READ) 


Specifies the program or learn sequence VAXTPU should execute whenever it 
receives a selection request event on a global selection it owns. 


FORMAT 


PARAMETERS _ buffert 


buffer? 
SET (GLOBAL_SELECT_READ, { ry i a 
, buffer2 


, learn_sequence 
, program 
l , range D) 
, string 
, NONE 


The buffer with which the global selection read routine is to be associated. 


SCREEN 


A keyword indicating that the specified routine is to be the application’s 
default global selection read routine. 


buffer2 


The buffer that contains the global selection read routine. If you do not 
specify this parameter, the global selection read routine is deleted. 


learn_sequence 


The learn sequence that specifies the global selection read routine. If you 
do not specify this parameter, the global selection read routine is deleted. 


program 
The program that specifies the global selection read routine. If you do not 
specify this parameter, the global selection read routine is deleted. 


range 
The range that contains the global selection read routine. If you do not 
specify this parameter, the global selection read routine is deleted. 


string 
The string that contains the global selection read routine. If you do not 
specify this parameter, the global selection read routine is deleted. 


NONE 


A keyword indicating that the global selection read routine should be 
deleted. 
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DESCRIPTION _ To specify a buffer-specific global selection read routine, use the buffer 
parameter. To specify a global selection read routine for the entire 
application, use the SCREEN keyword. 


When VAXTPU receives a request for information about a global selection 
it owns, it checks to see if the current buffer has a global selection read 
routine. If so, it executes that routine. If not, it checks to see if there is 
an application-wide global selection read routine. If so, it executes that 

- routine. If not, it tries to respond to the request itself. 


SIGNALED TPU$_BADKEY WARNING Y ified an invalid k d 
sf ou specified an invalid keywor 
ERRORS as a parameter. 
TPU$_INVPARAM ERROR One of the parameters was 
specified with data of the wrong 
type. 
TPU$_NORETURNVALUE ERROR The built-in cannot return a value. 
TPU$_REQSDECW ERROR You can use the built-in only if the 
DECwindows screen updater is in 
use. 
TPU$_TOOFEW ERROR Too few arguments passed to the 
built-in. 
TPU$_TOOMANY ERROR Too many arguments passed to 
the built-in. 
EXAMPLE The following statement designates the procedure uwser_read_global as a 


global selection read routine: | 
SET (GLOBAL SELECT READ, SCREEN, "user read_global"); 


For another example of code using the SET (GQLOBAL_SELECT_READ) 
built-in, see Example 5-1. 
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SET (GLOBAL SELECT TIME) 


Specifies how long VAXTPU should wait before it assumes that a request for 
information about a global selection will not be satisfied. 


FORMAT SET (GLOBAL_SELECT_TIME, SCREEN, 
integer ) 


string 


PARAMETERS GLOBAL SELECT TIME 
A keyword directing VAXTPU to set the expiration time for a global 
selection information request. 


SCREEN 


An optional keyword indicating that the top-level widget associated with 
VAXTPU’s screen is to receive the input focus. This keyword is the default. 


integer 
The number of seconds that VAXTPU should wait. 


string 
A string in VMS delta time format indicating how long VAXTPU should 
wait. 


DESCRIPTION The default waiting time is set by DECwindows. The maximum waiting 
time you can set is 24 days, 20 hours. 


SIGNALED TPU$_BADKEY WARNING ified an invalid k d 
= ou specified an invalid keywor 
ERRORS as a parameter. 

TPU$_INVTIME WARNING ~ You specified an invalid time 
interval. 

TPUS$_INVPARAM ERROR One of the parameters was 
specified with data of the wrong 
type. 

TPU$_NORETURNVALUE ERROR The built-in cannot return a value. 

TPU$_REQSDECW ERROR You can use the built-in only if the 
DECwindows screen updater is in 
use. 

TPU$_TOOFEW ERROR Too few arguments passed to the 
built-in. 

TPU$_TOOMANY ERROR Too many arguments passed to 

— the built-in. 
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EXAMPLE The following statement sets the waiting time for a global selection 
response to 3 seconds: 


SET (GLOBAL SELECT TIME, SCREEN, 3); 
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SET (GLOBAL SELECT UNGRAB) 


Specifies the program or learn sequence VAXTPU should execute whenever it 
loses ownership of a selection. 


FORMAT SET (GLOBAL_SELECT_UNGRAB, SCREEN 
, buffer 
, learn_sequence 
, program 
[ , range D) 
, string 
, NONE 


PARAMETERS _ buffer 
The buffer that contains the global selection ungrab routine. If you do 
not specify this parameter, the global selection ungrab routine is deleted 
and your application is not informed when VAXTPU gives up the global 
primary global selection. 


learn_sequence 

The learn sequence that specifies the global selection ungrab routine. If 
you do not specify this parameter, the global selection ungrab routine is 

deleted and your application is not informed when VAXTPU gives up the 
global primary global selection. 


program 

The program that specifies the global selection ungrab routine. If you do 
not specify this parameter, the global selection ungrab routine is deleted 
and your application is not informed when VAXTPU gives up the global 

primary global selection. 


range 

The range that contains the global selection ungrab routine. If you do 
not specify this parameter, the global selection ungrab routine is deleted 
and your application is not informed when VAXTPU gives up the global 
primary global selection. 


string 

The string that contains the global selection ungrab routine. If you do 
not specify this parameter, the global selection ungrab routine is deleted 
and your application is not informed when VAXTPU gives up the global 
primary global selection. © 


NONE 


A keyword directing VAXTPU to delete the current global selection ungrab 
routine. 
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SET (GLOBAL_SELECT_UNGRAB) 


DESCRIPTION For more information about VAXTPU’s global selection support, see 


Section 7.2. 
SIGNALED TPU$_BADKEY WARNING Y ified an invalid k d 
wi ou specified an invalid keywor 
ERRORS 3 as a parameter. 
TPU$_INVPARAM ERROR One of the parameters was 
specified with data of the wrong 
type. 
TPU$_NORETURNVALUE ERROR The built-in cannot return a value. 
TPU$_REQSDECW ERROR You can use the built-in only if the 
DECwindows screen updater is in 
use. 
TPU$_TOOFEW ERROR Too few arguments passed to the 
built-in. 
TPU$_TOOMANY ERROR Too many arguments passed to 
the built-in. 
EXAMPLE The following statement designates the procedure user_ungrab_global as a 


global selection ungrab routine: 


SET (GLOBAL SELECT _UNGRAB, SCREEN, "user _ungrab global"); 


For another example of code using the SET (GLOBAL_SELECT_ 


UNGRAB) built-in, see Example 5-1. 


a 
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SET (ICON NAME) 


Designates the string used as the layered application’s name in the 


DECwindows icon box. 


FORMAT SET (ICON_NAME, string) 


PARAMETERS /CON NAME 


A keyword instructing VAXTPU to set the text of an icon. 


string 


The text you want to appear in the icon. 


SIGNALED TPU$_INVPARAM ERROR One of th t 
- ne of the parameters was 
ERRORS specified with data of the wrong 
type. 
TPU$_NORETURNVALUE ERROR The built-in cannot return a value. 
TPU$_REQSDECW ERROR You can use the built-in only if the 
DECwindows screen updater is in 
use. 
TPU$_TOOFEW ERROR Too few arguments passed to the 
built-in. 
TPU$_TOOMANY ERROR Too many arguments passed to 
the built-in. 
EXAMPLE The following statement sets the text naming the layered application to be 


the string WordMonger. 


SET (ICON NAME, "“WordMonger") ; 
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SET (INPUT FOCUS) 


Requests the input focus. Ownership of the input focus determines which 
application or widget processes user input from the keyboard. 


FORMAT SET (INPUT FOCUS |: SCREEN | ) 
| | , Widget . 


PARAMETERS INPUT FOCUS 
A keyword directing VAXTPU to assign the input focus. 


SCREEN 


An optional keyword indicating that the top-level widget associated with 
VAXTPU’s screen is to receive the input focus. This keyword is the default. 


widget 

The widget that is to receive the input focus. Note that if you specify a 
widget for this parameter, the VAXTPU key bindings are not available to 
process keyboard input into the specified widget. 


DESCRIPTION This built-in requests that input focus be given to VAXTPU or to a 
widget that is part of an application layered on VAXTPU. It does not 
guarantee that VAXTPU or the widget will get the input focus. If VAXTPU 
or the widget receives the input focus, it gets a focus-in event. When 
VAXTPU gets this event, it calls the input focus grab routine. For more 
information about the role of events in DECwindows applications, see the 
VMS DECwindows Guide to Application Programming. 


When the top-level widget for VAXTPU’s screen has the input focus, 
VAXTPU processes keystrokes normally. That is, undefined printable 
keys insert characters in the current buffer, and defined keys execute the 
code bound to them. For more information on how VAXTPU processes 
keystrokes, see the VAX Text Processing Utility Manual. 


If a child widget in the widget hierarchy has the input focus, keystrokes 
are processed by that widget. For example, when a text widget in EVE’s 
replace dialog box has the input focus, keystrokes are processed by the 
text widget, not by VAXTPU. No VAXTPU key bindings are in effect. 


SIGNALED TPU$_BADKEY WARNING Y ified an invalid k d 
if ou specified an invalid keywor 
ERRORS as a parameter. 
TPU$_INVPARAM ERROR One of the parameters was 
specified with data of the wrong 
type. 
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TPU$ NORETURNVALUE ERROR The built-in cannot return a value. 

TPU$_REQSDECW ERROR You can use the built-in only if the 
DECwindows screen updater is in 
use. 

TPU$_TOOFEW ERROR Too few arguments passed to the 
built-in. 

TPU$_TOOMANY ERROR Too many arguments passed to 
the built-in. 

EXAMPLE The following procedure shows one possible way that a layered application 


can use the SET (INPUT_FOCUS) built-in. The procedure is a modified 
version of the EVE procedure eve$$widget_replace_okay. You can find 
the original version in SYS$EXAMPLES:EVE$MENUS.TPU. For more 
information about using the files in SYS$EXAMPLES as examples, see 
Section 7.7. 


Procedure eve$$widget_replace_ok fetches and tests the user’s responses to 
prompts for old and new replace strings. 


PROCEDURE eve$$widget_replace_ ok 


LOCAL new string, 
old string, 
old_str_text_widget, 
new str text widget; 


SET (INPUT FOCUS) ; ! This statement grabs input focus 
! so CTRL/C events will be detected. 


! Get the replace strings from the eve$$k_replace new_[old]text widgets. 


old str _ text widget := GET _INFO (WIDGET, "widget id", eve$x replace dialog, 
"REPLACE DIALOG.REPLACE OLD TEXT") 


old_ string := GET_INFO (old_str_ text_widget, "text"); 


! Test only the old string. 
Le’. old. string =" 


THEN 
eveSmessage (EVES NOREPLSTR) ; 
RETURN; 
ENDIF; 
new str text widget := GET INFO (WIDGET, "widget id", eve$x_replace dialog, 
"REPLACE DIALOG.REPLACE NEW TEXT") 
new string := GET INFO (new_str_text_widget, "text"); 
IF new string = "" 
THEN 
eveSSreplacel (old_string, new string, 1); 
ELSE 
eveSSreplacel (old_string, new _string); 
ENDIF; 
ENDPROCEDURBE; 


5-79 


VMS DECwindows VAXTPU Built-In Procedures 
SET (INPUT FOCUS GRAB) 


SET (INPUT FOCUS GRAB) 


Specifies the program or learn sequence that VAXTPU should execute 
whenever it-processes a focus-in event. 


FORMAT SET (INPUT_FOCUS_GRAB [, SCREEN 
, buffer 
, learn_sequence 
, program 
it nge My) 
, string 
, NONE 


PARAMETERS /INPUT_FOCUS_GRAB 


A keyword directing VAXTPU to set an attribute related to an input focus 
grab routine. 


SCREEN 


An optional keyword used to preserve compatibility with future versions of 
VAXTPU. This is the default. 


buffer 


The buffer that specifies the actions that VAXTPU should take whenever 
it processes a focus-in event. 


learn_sequence 


The learn sequence that specifies the actions that VAXTPU should take 
whenever it processes a focus-in event. 


program 
The program that specifies the actions that VAXTPU should take whenever 
it processes a focus-in event. 


range 
The range that specifies the actions that VAXTPU should take whenever it 
processes a focus-in event. 


string 
The string that specifies the actions that VAXTPU should take whenever 
it processes a focus-in event. 


NONE 


A keyword directing VAXTPU to delete the input focus grab routine. If you 
specify this keyword or do not specify the parameter at all, the application 
is not notified when input focus is received. 


DESCRIPTION For more information about VAXTPU’s input focus support, see Section 7.3. 
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SIGNALED TPU$_BADKEY WARNING Y ified an invalid k d 
a ou specified an invalid keywor 
ERRORS as a parameter. 
TPU$_INVPARAM ERROR One of the parameters was 
specified with data of the wrong 
type. 
TPU$_ NORETURNVALUE ERROR The built-in cannot return a value. 
TPU$_REQSDECW ERROR You can use the built-in only if the 
DECwindows screen updater is in 
use. 
TPU$_TOOFEW ERROR Too few arguments passed to the 
built-in. 
TPU$_TOOMANY ERROR Too many arguments passed to 
the built-in. 
EXAMPLE The following statement designates the procedure user_grab_focus as an 


input focus grab routine: 
SET (INPUT FOCUS GRAB, SCREEN, “user grab focus"); 


For another example of code using the SET (INPUT_FOCUS GRAB) 
built-in, see Example 5-1. 
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SET (INPUT FOCUS UNGRAB) 


Specifies the program or learn sequence that VAXTPU shouid execute 
whenever it processes a focus-out event. 


FORMAT SET (/INPUT_FOCUS_UNGRAB [, SCREEN 
, buffer 
, learn_sequence 
, program 
Di, nge Wy) 
, string 
, NONE 


PARAMETERS INPUT FOCUS UNGRAB 
A child ane VAXTPU to set an attribute related to an input focus 
ungrab routine. 


SCREEN . 
An optional keyword used to preserve compatibility with future versions of 
VAXTPU. This is the default. 


buffer 
The buffer that specifies the actions that VAXTPU should take whenever 
it processes a focus-out event. 


learn_sequence 
The learn sequence that specifies the actions that VAXTPU should take 
whenever it processes a focus-out event. 


program 
The program that specifies the actions that VAXTPU should take whenever 
it processes a focus-out event. 


range 
The range that specifies the actions that VAXTPU should take whenever it 
processes a focus-out event. 


string 
The string that specifies the actions that VAXTPU should take whenever 
it processes a focus-out event. 


NONE 


A keyword directing VAXTPU to delete the input focus ungrab routine. 
If you specify this keyword or do not specify the parameter at all, the 
application is not notified when input focus is lost. 


DESCRIPTION ‘Ror moneinformation about VAXTPU’s input focus support, see Section 7 
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SIGNALED TPU$_BADKEY WARNING ¥ ified an invalid k d 
s ou specified an invalid keywor 
ERRORS as a parameter. 
TPU$_INVPARAM ERROR One of the parameters was 
specified with data of the wrong 
type. 
TPU$_ NORETURNVALUE ERROR The built-in cannot return a value. 
TPU$_ REQSDECW ERROR You can use the built-in only if the 
DECwindows screen updater is in 
use. 
TPU$_ TOOFEW ERROR Too few arguments passed to the 
built-in. 
TPU$_TOOMANY ERROR Too many arguments passed to 
the built-in. 
EXAMPLE The following statement designates the procedure user_ungrab_focus as an 


input focus ungrab routine: 
SET (INPUT FOCUS UNGRAB, SCREEN, "user _ungrab focus"); 


For another example of code using the SET (INPUT FOCUS_UNGRAB) 
built-in, see Example 5-1. 
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SET (RESIZE ACTION) 


Specifies code to be executed when a resize event has occurred. Specifying 
a resize action routine overrides any previous resize action routines that have 
been defined. | 


FORMAT . , buffer 
, learn_sequence 
SET (RESIZE_ACTION ||? Program ) 
, range 
, string 
, NONE 


PARAMETERS RESIZE_ACTION 


A keyword directing VAXTPU to set an attribute related to a resize action 
routine. 


buffer 
The buffer that specifies the actions that VAXTPU should take whenever 
it is notified of a resize event. 


learn_sequence 
The learn sequence that specifies the actions that VAXTPU should take 
whenever it is notified of a resize event. 


program 
The program that specifies the actions that VAXTPU should take whenever 
it is notified of a resize event. 


range 
The range that specifies the actions that VAXTPU should take whenever it 
is notified of a resize event. 


string 
The string that specifies the actions that VAXTPU should take whenever 
it is notified of a resize event. 


NONE 


A keyword directing VAXTPU to delete the resize action routine. If you 
specify this keyword or do not specify the parameter at all, the application 
is not notified when a resize event occurs. 
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SIGNALED TPU$_INVPARAM ERROR One of th t 
ms ne of the parameters was 
ERRORS specified with data of the wrong 
type. 
TPU$ NORETURNVALUE ERROR The built-in cannot return a value. 
TPU$_REQSDECW ERROR You can use the built-in only if the 
DECwindows screen updater is in 
use. 
TPU$_TOOFEW ERROR Too few arguments passed to the 
built-in. 
TPU$_TOOMANY ERROR Too many arguments passed to 
the built-in. 
EXAMPLE The following statement specifies the procedure eve$$resize_action as the 


resize action routine. 
SET (RESIZE ACTION, “eveSSresize action"); 


To see this statement used in an initializing procedure, see the example in 
the description of the SET (SCREEN_LIMITS) built-in. 
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SET (SCREEN LIMITS) 


Specifies the minimum and maximum allowable sizes for the VAXTPU screen 
during resize operations. VAXTPU passes these limits to the DECwindows 
window manager, which is free to use or ignore the limits. 


FORMAT SET (SCREEN _LIMITS, array) 


PARAMETERS SCREEN LIMITS 
A keyword directing VAXTPU to pass hints to the DECwindows window 
manager about screen size. 


array 


An integer-indexed array using four elements to specify hints for the 
minimum and maximum screen width and length. The array indices and 
their corresponding elements are as follows: 


1 The minimum screen width, in columns. This value must be at least 
0 and less than or equal to the maximum screen width. The default 
value is 0. 


2 The minimum screen length, in lines. This value must be at least 
0 and less than or equal to the maximum screen length.The default 
value is 0. 


3 The maximum screen width, in columns. This value must be greater 
than or equal to the minimum screen width and less than or equal to 
255. The default value is 255. 


4 The maximum screen length, in lines. This value must be greater than 
or equal to the minimum screen length and less than or equal to 255. 
The default value is 255. 


SIGNALED 


TPU$_BADVALUE WARNING _ An integer parameter was 
ERRORS specified with a value outside 
the valid range. 


TPU$_MAXVALUE WARNING _ You specified a value higher than 
the maximum allowable value. 
TPU$_MINVALUE WARNING You specified a value lower than 


the minimum allowable value. 


TPU$_EXTRANEOUSARGS = ERROR One or more extraneous 
arguments has been specified 
for a DECwindows built-in. 


TPU$_INVPARAM ERROR One of the parameters was 
specified with data of the wrong 
type. 

TPU$_NORETURNVALUE ERROR The built-in cannot return a value. 
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TPU$_REQSDECW ERROR You can use the built-in only if the 

DECwindows screen updater is in 
use. 

TPU$_TOOFEW ERROR Too few arguments passed to the 
built-in. 

TPU$_TOOMANY ERROR Too many arguments passed to 
the built-in. 

TPU$_ REQARGSMISSING ERROR One or more required arguments 
is missing. 

EXAMPLE The following statements show one possible way that a layered application 


can use the SET (SCREEN_LIMITS) built-in. The statements are a 
portion of the EVE procedure eve$$decwindows_init. You can find the 
original version in SYS$SEXAMPLES:EVE$DECWINDOWS.TPU. For more 
information about using the files in SYS$EXAMPLES as examples, see 
Section 7.7. 


The procedure eve$$decwindows_init is the module initialization procedure 
for the package EVESDECWINDOWS. 


PROCEDURE eveS$$decwindows_init ! Module Initialization 
LOCAL temp array; 


eveSx decwindows active := GET INFO (SCREEN, "decwindows") ; 


IF NOT eveSx_decwindows active 
THEN 


RETURN (FALSE) 
ENDIF; 


! The following statements set the package up to handle resize actions. 


temp_array := CREATE ARRAY (4); 

temp array {1} := 20; ! Minimum width. 
temp array {2} := 6; ! Minimum height. 
temp array {3} := 250; ! Maximum width. 
temp_array {4} := 100; ! Maximum height. 


SET (SCREEN LIMITS, temp array); 
SET (RESIZE ACTION, “eveSS$resize action"); 
SET (ENABLE RESIZE, ON); | 


ENDPROCEDURE; 
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SET (SCROLL BAR) 


Enables a horizontal or vertical scroll bar for the specified window. 


FORMAT ee | := J SET ( SCROLL_BAR, window, 
widget 
HORIZONTAL, { ON \) 
VERTICAL, OFF 


PARAMETERS SCROLL _BAR 
A keyword directing VAXTPU to enable or disable a scroll bar in a 


VAXTPU window. 
window 
The window in which the scroll bar does or does not appear. 
HORIZONTAL 
A keyword directing VAXTPU to enable or disable a horizontal scroll bar. 
VERTICAL 
A keyword directing VAXTPU to enable or disable a vertical scroll bar. 
ON 
A keyword indicating that the scroll bar is to be visible in the specified 
window. 
OFF . 
A keyword indicating that the scroll bar is not to be visible in the specified 
window. 

return value 
integer The value 0 if an error prevents VAXTPU from associating a widget with 

the window. 

widget The widget instance implementing the vertical or horizontal scroll bar 


associated with a window. 


DESCRIPTION Scroll bars represent the location of the editing point in the buffer. By 
dragging the scroll bar’s slider, the user can reposition the editing point in 
the buffer mapped to the window. Scroll bars are unique among VAXTPU 
widgets in the following respects: 


e ach scroll bar widget is associated with a specific VAXTPU window. 
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e Instead of handling scroll widgets at the application level, you can 
direct the engine (VAXTPU’s internal routines, taken as a whole) to 
handle resizing and repositioning of the scroll bar slider. The engine 
always handles sizing and positioning of the scroll bar itself. 


Note that windows having fewer than four lines of text cannot display a 
vertical scroll bar. Similarly, a window less than four columns wide cannot 
display a horizontal scroll bar. 


SET (SCROLL_BAR) returns the scroll bar widget, or 0 if an error 
prevents VAXTPU from associating a widget with the window. 


By default, VAXTPU creates its windows without any scroll bars; using 
SET (SCROLL_BAR) with the keyword ON overrides the default. To make 
a scroll bar invisible after it has been placed in a window (for example, 

to allow the user of a layered application to turn off scroll bars), use SET 
(SCROLL_BAR) with the keyword OFF. 


When the size of a VAXTPU window changes, VAXTPU automatically 
adjusts the scroll bar to fit the new window size. 


The height of a vertical scroll bar represents the total number of lines in 
the buffer mapped to the window. 


The width of a horizontal scroll bar represents the greater of the following: 


e The width of the widest line in the set of lines visible in the window. 
“Width” means the distance from the first character on the line to the 
last character, regardless of whether all characters on the line are 
visible. 


e In a case where none of the lines in the set of lines visible in the 
window has text extending all the way to the rightmost window 
column, the width of the widest line from the first character on the 
line to the rightmost window column. 


Note that the horizontal scroll bar represents only the lines that are 
visible in the window, not all the lines in the buffer mapped to the window. 


SIGNALED 
ERRORS 


TPU$_BADKEY WARNING You specified an invalid keyword 
as a parameter. 

TPU$_INVPARAM ERROR One of the parameters was 
specified with data of the wrong 
type. 

TPU$_REQSDECW ERROR You can use the built-in only if the 
DECwindows screen updater is in 
use. 

TPU$_TOOFEW ERROR Too few arguments passed to the 
built-in. | 

TPU$_TOOMANY ERROR Too many arguments passed to 
the built-in. 
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EXAMPLE 


The following statement turns on a vertical scroll bar in the current 
window: 
vertical bar := SET (SCROLL BAR, CURRENT WINDOW, VERTICAL, ON); 


For sample code using the SET (SCROLL_BAR) built-in, see Example 7-7. 
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SET (SCROLL BAR AUTO THUMB) 


Enables or disables automatic adjustment of the scroll bar slider. 


FORMAT SET (SCROLL_BAR_AUTO_THUMB, window, 
i ; en \) 
VERTICAL | OFF 


PARAMETERS SCROLL_BAR_AUTO_THUMB 


A keyword directing VAXTPU to enable or disable automatic adjustment 
of the scroll bar slider in a VAXTPU window. 


window 
The window whose scroll bar slider you want VAXTPU to adjust. 


HORIZONTAL 
A keyword directing VAXTPU to set the slider on a horizontal scroll bar. 


VERTICAL 
A keyword directing VAXTPU to set the slider on a vertical scroll bar. 


ON 


A keyword directing VAXTPU to enable automatic adjustment of the scroll 
bar slider. 


OFF 
A keyword directing VAXTPU to disable automatic adjustment of the scroll 
bar slider. 


DESCRIPTION _ By default, SET (SCROLL_BAR_AUTO_THUMB) is set to ON and 
VAXTPU automatically manages a window’s scroll bar slider in the 
following ways: 


e Adjusts the size of the slider as the user adds, deletes, or moves text, 
so that the slider size represents the amount of visible text in relation 
to the total amount of text 


e Adjusts the size of the slider whenever the size of the window and 
the size of the scroll bar change, so that the slider size remains 
proportional to the scroll bar size 


e Adjusts the position of the slider as the user adds, deletes, or moves 
text, so that the slider shows whether the current buffer or line 
contains text not visible on the screen and, if so, where the invisible 
text is in relation to the visible text 
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When the scroll bar slider is adjusted automatically, the width of the slider 
in a horizontal scroll bar represents the width of the window. For example, 
the size of the slider changes when the window width is changed from 80 
to 132 columns or the reverse. The position of the slider changes when the 
window is shifted left or right. The height of the slider in a vertical scroll 
bar represents the height of the window. 


If you do not want VAXTPU to adjust the scroll bar slider automatically 
or if you want to change the size or position of the slider, specify the OFF 


keyword. For more information about calculating the size and position of 
the slider, see the description of the SET (SCROLL_BAR) built-in. 


Note that you cannot disable VAXTPU’s automatic adjustment of the scroll 


bar itself. 
SIGNALED TPU$_BADKEY WARNING Y ified an invalid k d 
= ou specified an invalid keywor 
ERRORS as a parameter. 

TPU$_INVPARAM ERROR One of the parameters was 
specified with data of the wrong 
type. 

TPU$_ NORETURNVALUE ERROR The built-in cannot return a value. 

TPU$_REQSDECW ERROR You can use the built-in only if the 
DECwindows screen updater is in 
use. 

TPU$_TOOFEW ERROR Too few arguments passed to the 
built-in. 

TPU$_TOOMANY ERROR Too many arguments passed to 

| the built-in. 

EXAMPLE The following statement turns on automatic adjustment of the vertical | 
scroll bar’s slider in the current window: 
vertical_bar := SET (SCROLL _BAR_AUTO THUMB, CURRENT WINDOW, VERTICAL, ON); 


For sample code using the SET (SCROLL_BAR_AUTO_THUMB) built-in, 
see Example 7-7. 


5-92 


VMS DECwindows VAXTPU Built-In Procedures 
SET (TEXT) 


SET (TEXT) 


Sets the text of the specified widget of class SText to be the specified string. 


For more information about widget classes, see the VMS DECwindows Toolkit 
Routines Reference Manual. 


FORMAT SET (TEXT, widget, string) 


PARAMETERS TEXT 
A keyword directing VAXTPU to set an attribute related to text 
manipulation. 


widget 


The widget instance whose text you want to set. 


string 
The text you want to assign to the simple text widget. 


SIGNALED TPU$_BADKEY WARNING Y ified an invalid k d 
- 3 ou specified an invalid keywor 
ERRORS as a parameter. 
TPUS$_INVPARAM ERROR One of the parameters was 
specified with data of the wrong 
type. 
TPU$_NORETURNVALUE ERROR The built-in cannot return a value. 
TPU$_ REQSDECW ERROR You can use the built-in only if the 
DECwindows screen updater is in 
use. 
TPU$_TOOFEW ERROR Too few arguments passed to the 
built-in. 
TPU$_TOOMANY ERROR Too many arguments passed to 
the built-in. 
TPU$_WIDMISMATCH ERROR The specified widget is not of class 
SText. 


DESCRIPTION — SET (TEXT, widget, string) is equivalent to the XUI Toolkit routine dwt$s_ 
text_set_string. 


EXAMPLES 


SET (TEXT, user text widget, "No default string available."); 


Assuming that the variable user_text_widget has been assigned a text 
widget instance, this statement causes the widget to display the text No 
default string available. 
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SET (TEXT) 
2 wildcard dialog box := GET INFO (WIDGET, "widget _id", 
evesx | wildcard find dialog, 
"WILDCARD FIND | DIALOG. WILDCARD FIND TEXT") ; ; 
status := SET (TEXT, wildcard dialog box, eve$x_target); 


These statements show one possible way that a layered application can 
use the SET (TEXT) widget. The variable eve$x_target stores the string 
Gif one exists) that the user specified as the wildcard search string the 
last time the user invoked the wildcard find dialog box. The SET (TEXT) 
statement directs EVE’s wildcard find dialog box widget to display the 
string assigned to eve$x_target. 
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SET (WIDGET) 


Allows you to assign values to various resources of a widget. 


FORMAT SET (WIDGET, widget, 


array ) 
name_and_value J, name_and_value ... ] \ 


PARAMETERS WIDGET 
A keyword directing VAXTPU to set an attribute of a widget. 


widget 


The widget instance whose values you want to set. 


array 

An array specifying the resources whose values are to be set. Each 
array index must be a string naming a valid resource for the specified 
widget. Note that resource names are case-sensitive. The value in the 
corresponding array element is passed to the widget. The array can 
contain any number of elements. 


name_and_value 
A string naming a valid resource for the widget followed by the value that 
you want to assign to the resource. Use the following format: 


resource name string, resource value 


DESCRIPTION This built-in is functionally equivalent to the XUI Toolkit routine SET 
VALUES. 


If you specify the name of a resource that the widget does not support, 
VAXTPU signals the error TPU$_ARGMISMATCH. 


For more information about specifying resources, see Chapter 6. 


SIGNALED TPU$_BADKEY WARNING ¥ ified an invalid k d 
s ou specified an invalid keywor 
ERRORS as a parameter. 
TPU$_ARGMISMATCH ERROR You have specified an 


_unsupported class of widget or 
a value whose data type is not 


supported. 
TPU$_NORETURNVALUE ERROR The built-in cannot return a value. 
TPU$_REQSDECW ERROR You can use the built-in only if the 
DECwindows screen updater is in 
use. 
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TPU$_TOOFEW ERROR Too few arguments passed to the 
built-in. 

TPU$_TOOMANY ERROR Too many arguments passed to 
the built-in. 

TPU$_WIDMISMATCH ERROR You have specified a widget whose 


class is not supported. 


EXAMPLE The following statements set the Nvalue resource of the current window’s 
scroll bar widget to 100. This causes the scroll bar slider to be displayed 
as far toward the bottom of the scroll bar widget as possible. 


scroll bar widget := SET (SCROLL BAR, CURRENT WINDOW, VERTICAL, ON); 
SET (WIDGET, scroll bar widget, eve$dwt$c Nvalue, 100); 


For an example of a procedure using the SET (WIDGET) built-in, see 
Example 7-8. 
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SET (WIDGET CALLBACK) 


Specifies the VAXTPU program or learn sequence to be called by VAXTPU 
when a widget callback occurs for the widget instance. 


FORMAT SET (WIDGET_CALLBACK, widget, 
buffer, 
learn_sequence, 
program, closure ) 
range, 
string, 


PARAMETERS WIDGET CALLBACK 
A keyword directing VAXTPU to set the application-level widget callback. 


widget 


The widget instance whose callback you want to set. 


buffer 


The buffer that contains the application-level callback routine. This code 
is executed when the widget performs a callback to VAXTPU. 


learn_sequence 
The learn sequence that specifies the application-level callback routine. 
This code is executed when the widget performs a callback to VAXTPU. 


program 
The program that specifies the application-level callback routine. This 
code is executed when the widget performs a callback to VAXTPU. 


range 
The range that contains the application-level callback routine. This code 
is executed when the widget performs a callback to VAXTPU. 


string 
The string that contains the application-level callback routine. This code 
is executed when the widget performs a callback to VAXTPU. 


closure | 

A string or integer. VAXTPU passes the value to the application when the 
widget performs a callback to VAXTPU. For more information about using 
closures, see Chapter 6. 
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SIGNALED | | i 

ERRORS TPU$_ARGMISMATCH ERROR The data type of the indicated 
parameter is not supported by the © 
built-in. 

TPU$_BADDELETE ERROR You are attempting to modify an 
integer, a keyword, or a string 
constant. 

TPU$_TOOFEW ERROR Too few arguments passed to the 
built-in. 

TPU$_TOOMANY ERROR Too many arguments passed to 
the built-in. 

TPU$_COMPILEFAIL WARNING ~ Program compilation has been 
terminated because of a syntax 
error. 

EXAMPLE The following statement designates the EVE procedure eve$scroll_dispatch 


as the callback routine for the widget scroll_bar_widget and assigns to the 
callback the closure value ‘h’. 


SET (WIDGET CALLBACK, scroll _ bar widget, "“eveSscroll dispatch", ‘h’); 


For a procedure using this statement while mapping windows see 
Example 7—7. 
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UNMANAGE_ WIDGET 


Makes the specified widget and all of its children invisible. 


For more information about managing widgets, see the VMS DECwindows 
Toolkit Routines Reference Manual. 


FORMAT 


UNMANAGE WIDGET (widget, widget... J) 


PARAMETERS _ widget 


The widget instance to be unmanaged. 


DESCRIPTION __ If you want to unmanage several widgets that are children of the same 
parent, but you do not want to unmanage the parent, include all the 
children in a single call to UNMANAGE_WIDGET. Unmanaging several 
widgets at once is more efficient than unmanaging one widget at a time. 
The UNMANAGE WIDGET built-in is equivalent to the XUI Toolkit 
UNMANAGE CHILD and UNMANAGE CHILDREN routines. 

SIGNALED TPU$_INVPARAM ERROR Y ified ter of th 

i ou specified a parameter of the 

ERRORS wrong type. 

TPU$_TOOFEW ERROR Too few arguments passed to the 
built-in. 

TPU$_NORETURNVALUE ERROR The built-in cannot return a value. 

TPU$_ REQSDECW ERROR You can use the built-in only if the 
DECwindows screen updater is in 
use. 

TPU$_WIDMISMATCH ERROR You have specified a widget whose 
class is not supported. 

EXAMPLE The following procedure shows one possible way that a layered application 


can use the UNMANAGE_WIDGET built-in. The procedure is a modified 
version of the EVE procedure eve$$replace_clean_up. You can find 

the original version in SYS$SEXAMPLES:EVE$EDIT.TPU. For more 
information about using the files in SYS$EXAMPLES as examples, see 
Section 7.7. 


The procedure performs screen cleanup operations after the user has used | 
the EVE command REPLACE. It restores the direction and mode to which 
the buffer was set before the replace operation began, then tests whether 
the replace dialog box is present and, if so, makes it invisible. 
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PROCEDURE eveS$Sreplace clean _up 


ON ERROR 
[TPUS CONTROLC] : 
eveSlearn_ abort; 
abort; 
[OTHERWISE] : 
eveS$replace_ error handler; 
ENDON_ERROR; 


IF NOT eveS$x_replace array {eve$$k_replace_asking} 


THEN ! If all occurrences were replaced, the editing 
! point is positioned to the last saved _ mark. 


POSITION (eveS$x_replace array {eve$$k_replace_saved_mark}); 
ENDIF; 


! Restore the buffer’s original direction and mode. 


SET (eve$$x_replace array {eve$$k_ replace _saved_ direction}, 
eve$$x_ replace array {eve$$k_replace this buffer}); 

SET (eve$$x_ replace array {eveS$k_replace saved _mode}, 
eve$$x_replace array {eve$$k_replace this buffer}); 


SET (SCREEN UPDATE, ON) ; 
eveSmessage (EVES REPLCOUNT, 0, 
eveS$x_ replace array {eve$$k_replace occurrences}) ; 


a 


IF (eveS$x_ state array {eve$$k_command_line flag} = eve$k_invoked_by menu) 
AND (eve$S$x_state_array {eve$$k_dialog_ box}) 
THEN 
IF eve$x_decwindows active 
THEN 
IF GET INFO (eveSx_ replace each dialog, "type") = WIDGET 
THEN 
UNMANAGE WIDGET (eve$x_replace_ each dialog) ; ! This statement 


! unmanages the 
! replace dialog 
! box. 
ENDIF; 
ENDIF; 
ENDIF’; 


ENDPROCEDURE; 
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WRITE_CLIPBOARD 


Writes STRING format data to the clipboard. 


FORMAT buffer 
WRITE_CLIPBOARD (clipboard_label, ; range }) 
string 


PARAMETERS - clipboard_label 
The label for multiple entries in the clipboard. Since the clipboard does 
not currently support multiple labels, use any string including the null 
string to specify this parameter. 


buffer 

The buffer containing text to be written to the clipboard. VAXTPU 
represents line breaks by a line-feed character (ASCII (10)). If you specify 
a buffer, VAXTPU converts the buffer to a string, replacing line breaks 
with line feeds, and replacing the white space before the left margin with 
padding blanks. 


The buffer must contain at least one character or line break. If it does not, 
VAXTPU signals TPU$_CLIPBOARDZERO. 


range 

The range containing text to be written to the clipboard. VAXTPU 
represents line breaks by a line-feed character (ASCII (10)). If you specify 
a range, VAXTPU converts the range to a string, replacing line breaks 


with line feeds, and replacing the white space before the left margin with 
padding blanks. 


The range must contain at least one character or line break. If it does not, 
VAXTPU signals TPU$_CLIPBOARDZERO. 


str, Ing 

The string containing text to be written to the clipboard. The string must 
contain at least one character. If it does not, VAXTPU signals TPU$_ 
CLIPBOARDZERO. 


DESCRIPTION The clipboard_label parameter provides support for multiple entries on 
the clipboard; however, at present, the clipboard does not support multiple 
entries. 


SIGNALED TPU$ CLIPBOARDLOCKED WARNING The clipboard is locked b th 
e cilpdoarad IS ioCcCKe anotiner 
ERRORS = P % 


process. 
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TPU$_CLIPBOARDZERO WARNING _ The data to be written to the 
clipboard has zero length. 

TPU$_ TRUNCATE WARNING ~~ VAXTPU has truncated characters 
from the data written because 
you specified a buffer or range 
containing more than 65,535 
characters. 

TPU$_INVPARAM ERROR One of the parameters was 
specified with data of the wrong 
type. 

TPU$ NORETURNVALUE ERROR The built-in cannot return a value. 

TPU$_REQSDECW ERROR You can use the built-in only if the 
DECwindows screen updater is in 
use. 

TPU$_TOOFEW ERROR Too few arguments passed to the 
built-in. | 

TPU$_TOOMANY ERROR Too many arguments passed to 
the built-in. 

EXAMPLES For an explanation of the VAXTPU code in these examples, see the 
paragraph following each numbered code example. 
WRITE CLIPBOARD ("", this range); 
This statement writes the contents of the range this_range to the 
clipboard. 
2 PROCEDURE eveS$cut_ copy (delete range) 
LOCAL remove range, ! Local copy of the currently 
! selected range. 
done message; ! Success message. 
ON ERROR 


[TPUS CLIPBOARDLOCKED] : 


eveSmessage (EVES CLIPBDWRITLOCK) ; 


eveSlearn abort; 
RETURN (FALSE) ; 
[OTHERWISE] : 
eveSlearn_abort; 
ENDON ERROR; 
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remove range := eveSselection (TRUE); 
IF remove_range <> 0 
THEN 
WRITE CLIPBOARD ("", remove range); ! This statement writes a copy 
! of the selected range to the 
! clipboard. 
IF delete range 
THEN 
done_message := EVES REMCOMPL; 
ERASE (remove range) ; 
ELSE 
done_ message := EVES COPYCOMPL; 
ENDIF; 
remove range := 0; 


eveSmessage (done message) ; 
RETURN (TRUE) ; 
ENDIF; 


eveSlearn_ abort; 
RETURN (FALSE) ; 


ENDPROCEDURE; 


This procedure shows one possible way that a layered application 

can use the WRITE_CLIPBOARD built-in. This procedure is a copy 
of the EVE procedure eve$$cut_copy. You can find this procedure in 
SYS$SEXAMPLES:EVE$DECWINDOWS.TPU. For more information on 
using the files in SYS$SEXAMPLES as examples, see Section 7.7. 


The procedure checks whether a selection is active and, if so, writes the 
contents of the selected range to the clipboard. If the user has directed 
EVE to cut the selected text, the procedure erases the selected range. 
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WRITE_GLOBAL_SELECT 


Sends requested information about a global selection from the VAXTPU 
layered application to the application that issued the information request. 


array 
buffer 

WRITE_GLOBAL SELECT /( bos ) 
integer 
NONE 


FORMAT 


PARAMETERS @4/ray 


An array passing information about a global selection whose contents 
describe information that is not of a data type supported by VAXTPU. For 
example, the array could pass information about a pixmap, an icon, or a 
span. 


VAXTPU does not use or alter the information in the array; the application | 
layered on VAXTPU is responsible for determining how the information 

is used, if at all. Since the array is used to pass information to and from 
other DECwindows applications, all applications that will send or receive 
information whose data type is not supported by VAXTPU must agree on 
how the information is to be sent and used. 


The application sending the information is responsible for creating the 
array and giving it the proper structure. The array’s structure is as 
follows: 


° The element array {0} contains a string naming the data type of 
the information being passed. For example, if the information being 
passed is a span, the element contains the string "SPAN". 


¢ The element array {1} contains either the integer 8, indicating that the 
information is passed as a series of bytes, or the integer 32, indicating 
that the information is passed as a series of longwords. 


e If array {1} contains the value 8, the element array {2} contains a 
string and there are no array elements after array {2}. The string 
does not name anything, but rather is a series of bytes. As mentioned, 
the meaning and use of the information is agreed upon by convention 
among the DECwindows applications. 


e Ifarray {1} contains the value 32, the element array {2} contains an 
integer. In this case, the array can have any number of elements after 
array {2}. These elements must be numbered sequentially, starting at 
array {3}. All the elements contain integers. Each integer represents a 
longword of data. To determine how many longwords are being passed, , 
an application can determine the length of the array and subtract 2 to \ 
allow for elements array {0} and array {1}. 
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buffer 


The buffer containing the information to be sent to the requesting 
application as the response to the global selection information request. 

If you specify a buffer, VAXTPU converts the buffer to a string, converts 
line breaks to line feeds, and inserts padding blanks before text to fill any 
unoccupied space before the left margin. 


range 

The range containing the information to be sent to the requesting 
application as the response to the global selection information request. 

If you specify a range, VAXTPU converts the buffer to a string, converts 
line breaks to line feeds, and inserts padding blanks before and after text 
to fill any unoccupied space before the left margin. 


string 

The string containing the information to be sent to the requesting 
application as the response to the global selection information request. 
VAXTPU sends the information in string format. 


integer 

An integer whose value is to be sent to the requesting application as the 
response to the global selection information request. VAXTPU sends the 
information in integer format. 


NONE 


A keyword indicating that no information about the global selection is 
available. 


WRITE_GLOBAL_SELECT is valid only inside a routine that responds to 
requests for information about a global selection. 

The parameter specifies the data to supply to the requesting application. 
If you specify NONE, VAXTPU informs the requesting application that 
no information is available. Note, however, that for any case in which a 
routine omits a WRITE_GLOBAL_SELECT statement, by default VAXTPU 
informs the requesting application that no information is available. 


Call WRITE_GLOBAL_SELECT no more than once during the execution 
of a global selection read routine. It signals TPU$_INVBUILTIN if you 
attempt to call this routine more than once. 


TPU$ BUILTININV WARNING WRITE_GLOBAL_SELECT has 
been used more than once in the 
same routine. 


TPU$_TRUNCATE WARNING  VAXTPU has truncated characters 
from the data written because 
you specified a buffer or range 
containing more than 65,535 
characters. 
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TPU$_INVPARAM ERROR One of the parameters was 
specified with data of the wrong 
type. 

TPU$_NORETURNVALUE ERROR The built-in cannot return a value. 

TPU$_REQSDECW ERROR You can use the built-in only if the 
DECwindows screen updater is in 
use. 

TPU$_TOOFEW ERROR Too few arguments passed to the 
built-in. 

TPU$_TOOMANY ERROR Too many arguments passed to 
the built-in. 

EXAMPLE The following statement sends the contents of the range this_range to the 


requesting application. 
WRITE GLOBAL SELECT (this range) ; 


For an example of a procedure using the WRITE_GLOBAL_SELECT 
built-in, see Example 7-11. 
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This chapter provides information useful for programmers who extend 
EVE or layer applications on EVE. 


For more information about using the DECwindows EVE editor, see the 
VMS Version 5.1 Release Notes. 


6.1 screen Objects in Applications Layered on DECwindows VAXTPU 


Figure 6-1 and its accompanying text show the nomenclature for the 
screen objects used in EVE and, optionally, in other applications layered 
on VAXTPU. 
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Figure 6-1 Nomenclature of DECwindows VAXTPU Screen Objects 


File Edit | Search Format ‘Display Customize 


[een anne ENRERRER [°)| 


Buffer: EMPTY.TXT. - . 


Buffer: SAMPLE.TXT == «= | Write | Insert. |) Forward 


ZK-0239A-—GE 


Key to Figure 6-1 


1 Display—In VAXTPU, the term display refers to the physical display device on 
which screen objects are visible. 
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2 Main window widget—This widget is created by VAXTPU, not by the layered 
application. Although the main window widget is not visible as a separate entity, 
itis the ancestor of all of EVE’s visible widgets. The VAXTPU SCREEN keyword, 
when used as a parameter to a widget-related built-in, refers to the main window 
widget. 


VAXTPU’s main window widget is associated with a DECwindows window. Both 
DECwindows and VAXTPU have objects called “windows.” VAXTPU windows 
have much the same function as DECwindows windows, but VAXTPU windows 
operate within a more limited scope. 


A DECwindows window is a viewport enabling a DECwindows application to 
make visible some text and graphics. For example, a DECwindows window can 
be used as a viewport onto a widget. A DECwindows window is mapped to an 
area on a physical display device. For more information about DECwindows 
windows, see the VMS DECwindows Guide to Application Programming. 


A VAXTPU window is a viewport onto a VAXTPU buffer. VAXTPU windows 
always have the same width as the VAXTPU screen. For more information about 
the VAXTPU screen, see item 3 in this key. You can map a VAXTPU window 
only within an area of the physical display device occupied by a VAXTPU screen. 
For more information about mapping VAXTPU windows, see the VAX Text 
Processing Utility Manual. 


3 VAXTPU screen—This widget is created by VAXTPU, not by the layered 
application. When you use the SCREEN keyword as a parameter to a built- 
in unrelated to widgets, the keyword refers to the VAXTPU screen. In the 
character-cell version of VAXTPU, the phrase “VAXTPU screen” means all the 
area visible on the physical terminal screen. 


4 Title bar—The title bar for EVE (or any other application layered on VAXTPU) is 
created by DECwindows, not by VAXTPU or the layered application. 


5 Menu bar—The EVE menu bar widget is created by EVE, not by VAXTPU. You 
can optionally create a menu bar widget in any application layered on VAXTPU. 
If you do so, make the menu bar widget a child of the VAXTPU main window 
widget. 

6 EVE user window—This window is created by EVE and is mapped to a buffer. 
It is a VAXTPU window, not a widget. Other applications layered on VAXTPU 
should create one or more user windows in which to display the results of your 
actions. 


7 EVE command window—This window is created by EVE. It is a VAXTPU window, 
not a widget. Other applications layered on VAXTPU can optionally create a 
command window. 


8 EVE message window—This window is created by EVE. It is a VAXTPU window, 
not a widget. Other applications layered on VAXTPU can optionally create a 
message window. 


6.2 Select Ranges in DECwindows EVE 


This section is intended for programmers extending EVE or layering an 
application on EVE. 


EVE can use only one type of selection at a time. There are four possible 
types of selection: dynamic selections, static selections, found range 
selections, and DECwindows primary global selections. The ways in which 
these selections differ are explained in the following sections. 
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EVE has a routine called EVE$SELECTION that returns the current 
selection, regardless of whether the selection is dynamic, static, or 
formed from a found range. It is possible to use the VAXTPU built- 

in SELECT_RANGE to obtain the current selection if the selection is 
a dynamic selection. However, DIGITAL recommends that you use 
EVE$SELECTION to obtain the current selection, because this routine 
returns the current selection regardless of how it was created. 


6.2.1. Dynamic Selections 


6.2.2 Static Selections 
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When you press the SELECT key or invoke the EVE command SELECT, 
EVE creates a dynamic selection. A dynamic selection expands and 
contracts as you move the text cursor. Moving the text cursor away from 
the text already selected does not cancel the selection. If you use the 
mouse to start a selection while a dynamic selection is active, the dynamic 
selection is canceled. 


If EVE’s current selection is a dynamic selection, the routine 
EVE$SELECTION returns the selected range and terminates the 
selection. If, for some reason, you want to use a statement that returns 
the current dynamic selection but does not terminate it, you can use a 
statement whose format is similar to the following: 


rl := EVESSELECTION (TRUE, TRUE, TRUE, TRUE, FALSE) 


The last parameter directs EVE$SELECTION not to terminate the 


selection. 


EVE creates a static selection if you do any of the following: 


¢ Click the MB1 mouse button two or more times to select a word, line, 
paragraph, or buffer 


e Use the EVE command SELECT ALL 


e Press the MB1 mouse button, drag the mouse across text, and then 
release the mouse button 


e Use the MB1 mouse button with the SHIFT key to extend a selection 


EVE implements a static selection by creating a range upon which you can 
perform EVE commands such as STORE TEXT or REMOVE. However, 
EVE does not start this range using the VAXTPU built-in SELECT. Thus, 
if you use the SELECT_RANGE built-in while a static selection is active, 
VAXTPU returns the message “No select active.” 


If you move the text cursor off the text in the static selection, the selection 
is canceled. 
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6.2.3. Found Range Selections 


When EVE positions to the beginning of a range as the result of the FIND 
command, WILDCARD FIND command, or pressing the FIND key, EVE 
creates a found range containing the text EVE found as a match for your 
search string. If no dynamic selection is active, EVE treats the found 
range as the current selection. 


EVE implements a found range selection by creating a range upon which 
you can perform EVE commands such as STORE TEXT or REMOVE. 
However, EVE does not start this range using the VAXTPU built-in 
SELECT. Thus, if you use the SELECT_RANGE built-in while a found 
range selection is active, VAXTPU returns the message “No select active.” 


If you move the text cursor off the text in the found range selection, the 
selection is canceled. 


6.2.4 Relation of EVE Selection to DECwindows Global Selection 


If EVE has a dynamic selection or a static selection active, that selection 
is automatically designated as the primary global selection. A found range 
selection is not designated as the primary global selection. 


You can use the routine EVE$SELECTION to obtain the text of the 
primary global selection when an application other than VAXTPU owns 
the selection. To do so, the call to EVESSELECTION must be in code 
bound to a mouse button other than MB1. The value returned is a string 
containing the text of the primary global selection. 
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7 Programming in DECwindows VAXTPU 


This chapter provides information about various aspects of programming 
with DECwindows VAXTPU. 


7.1 Widgets Supported by DECwindows VAXTPU 


DECwindows VAXTPU enables you to create widgets from within VAXTPU 
programs using the CREATE_WIDGET built-in. For information about 
how to use widgets to create a DECwindows text processing interface, see 
the XUI Style Guide and the VMS DECwindows Guide to Application 
Programming. For information about the characteristics of specific 
widgets, see the VMS DECwindows Toolkit Routines Reference Manual. 


Using the CREATE_WIDGET built-in, you can create the following 
widgets in VAXTPU: 


¢ Caution_box 

¢ Dialog box 

e File selection 

e Label 

e List_box 

¢ Main_window 

¢ Menu_bar 

¢ Popup_attached_db 
e Popup_dialog_box 

e Popup_menu 

¢ Pulldown_entry 

e =Pulldown_menu 

¢ Push_button 

e Scroll_bar (vertical and horizontal) 
¢ Separator 

e Simple_text 

¢ Toggle button 
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Global Selection Support in DECwindows VAXTPU 


Global selection in VMS DECwindows is a means of preserving 
information selected by the user so the user’s selection, or data about 
the user’s selection, can be passed between DECwindows applications. 
Each DECwindows application can own one or more global selections. 


Difference Between Global Selection and Clipboard 


A global selection differs from the clipboard in that the global selection 
changes dynamically as the user changes the select range, while the 
contents of the clipboard remain unchanged until the user uses a command 
(such as the EVE STORE TEXT command) that sends new information to 
the clipboard. 


Handling of Multiple Global Selections 
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Each global selection is owned by at most one DECwindows application; 
a global selection can also be unowned. A DECwindows application can 
own more than one global selection at the same time. For example, an 
application layered on VAXTPU can own both the primary and secondary 
global selection properties. The DECwindows server determines which 
application owns which global selection. 


Information about a global selection property may be stored in different 
formats, but the format of a particular piece of information must be 

the same for all DECwindows applications. VAXTPU directly accepts 
information that is stored in integer or string format. VAXTPU handles 
information in other formats by describing the information in an array. 
For more information about this use of an array, see the descriptions of 
the built-ins GET_GLOBAL_SELECT and WRITE_GLOBAL_SELECT in 
Chapter 5. 


Global selections are identified in VAXTPU either as strings or keywords. 
While DECwindows provides for many global selections, applications 
conforming to the XUI Style Guide are concerned with only two selections, 
the primary and secondary selections. VAXTPU provides a pair of 
keywords (PRIMARY and SECONDARY) to refer to these selections. 
VAXTPU also provides built-in procedures that allow layered applications 
to manipulate global selection information. 


You can refer to other global selections by specifying a string instead of the 
keywords PRIMARY and SECONDARY. For example, if your application 
has a global selection whose name is auxiliary, specify the selection using 
the string "auxiliary." Note that selection names are case sensitive; the 
string "auxiliary" does not refer to the same global selection as the string 
"AUXILIARY." 
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7.2.3 Relation of Global Selection to Input Focus 


An application that conforms to the XUI Style Guide requests ownership of 
the primary global selection in its input focus grab procedure. Regardless 
of whether the application conforms, when VAXTPU obtains ownership 

of the input focus, it automatically grabs ownership of the primary global 
selection if it is not already the owner. An application cannot prevent 
VAXTPU from attempting to assert ownership of the primary global 
selection when VAXTPU receives the input focus. If you are attempting 

to write an application that conforms to the XUI Style Guide and you find 
that VAXTPU has had to grab ownership and execute the global selection 
routine automatically, your application may have a design problem. 


Once VAXTPU owns the primary global selection, it automatically executes 
the application’s global selection grab routine if one is present. 


7.2.4 Response to Requests for Information About the Global Selection 


VAXTPU provides a three-level hierarchy for responding to requests 
from another application for information about the current selection. 
Applications layered on VAXTPU may specify a routine that responds 

to requests for information about global selections either for the entire 
application or for one or more buffers in the application. When VAXTPU 
receives a request for information, it checks whether there is a routine for 
the current buffer that responds to information about global selections. If 
no buffer-specific routine is available, VAXTPU checks for an application- 
wide routine. If no application-wide routine is available, VAXTPU 
attempts to respond to the request itself, but it can only respond to 
requests for information about the primary selection and only provides 
information about the file name, font, line number, and text. VAXTPU 
responds to all other requests with a message that no information is 
available. Note that VAXTPU does not send requests for information 
about the global selection to other DECwindows applications. 


VAXTPU’s responses to requests for information about the primary 
selection are as follows: 


"FILE NAME" VAXTPU responds with the string returned by the built-in 
procedure GET_INFO (CURRENT _BUFFER, "file_name"). 

"FONT" VAXTPU responds with the string returned by the built-in 
procedure GET_INFO (SYSTEM, "default_font"). 

"LINE_ NUMBER" VAXTPU responds with value of type SPAN containing the 


record number where the select range starts and the record 
number where the select range ends. 


"TEXT" or VAXTPU responds with the text of the select range as a 
"STRING" string, with each line break represented by a line feed. 


DIGITAL recommends that you not use a non-DECwindows section file 
with the DECwindows version of VAXTPU. However, if you do not follow 
this recommendation, VAXTPU’s automatic grabbing of the primary 
global selection allows your layered application to interact with other 
DECwindows applications. If an application requests information about 
the primary global selection while VAXTPU owns the selection, VAXTPU 
attempts to respond to the request if the application cannot do so. If 
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VAXTPU responds to the request by sending the text of a buffer or range, 
VAXTPU converts the buffer or range to a string, converts line breaks to 
line feeds, and inserts padding blanks before text to fill any unoccupied 
space between the margins. If neither the application nor VAXTPU can 
respond to the request, VAXTPU informs DECwindows that the requested 
information is not available. 


VAXTPU does not automatically grab the secondary selection. Layered 
applications are responsible for handling this selection. 


7.3 Input Focus Support in DECwindows VAXTPU 


In VMS DECwindows, at most one of the applications on the screen can 
have the input focus; that is, an application can have the ability to accept 
user input from the keyboard. For more information about the input focus, 
see the XUI Style Guide. 


DECwindows VAXTPU automatically grabs the input focus whenever the 
user causes an unmodified M1DOWN event (that is, an event not modified 
by SHIFT, CTRL, or other modifying key) while the pointer cursor is in 
either of the following locations: 


¢ VAXTPU’s main window widget 
¢ VAXTPU’s title bar 


When DECwindows VAXTPU grabs input focus or when an application 
layered on VAXTPU requests input focus, DECwindows assigns the focus 
to VAXTPU only if and when it is possible to do so. Therefore, your 
application should use the GET_INFO (SCREEN, “input_focus") built- 
in to test whether it actually has the input focus before performing any 
operation that requires the input focus. 


DIGITAL recommends that you not use a non-DECwindows section file 
with the DECwindows version of VAXTPU. However, if you do not follow | 
this recommendation, VAXTPU’s automatic grabbing of the input focus 
allows your layered application to interact with other applications in a 
DECwindows environment. 


7.4 Using Callbacks in DECwindows VAXTPU 


When the user performs an action affecting a widget, the widget sends 

a callback, or notification, to the application of which the widget is a 
part. The callback is sent to a callback routine, which is the portion of 
the application that defines what the application does in response to the 
callback. For more information about the use of callbacks and callback 
routines in DECwindows programs, see the VMS DECwindows Guide to 
Application Programming. 


There are many possible ways to design an application layered on 
DECwindows VAXTPU. Therefore, there is no single “right” way to handle , 
callbacks when creating a layered application. However, the following \ 
information describing the relationship between the VAXTPU engine and 

a layered application is helpful for the programmer who is layering an 
application with a DECwindows interface on VAXTPU. 


(—4 


Programming in DECwindows VAXTPU 
7.4 Using Callbacks in DECwindows VAXTPU 


Creating an application layered on VAXTPU can involve the following 
different levels of mechanisms for handling callbacks: 


¢ Callable interface-level callback routines—Routines internal to 
VAXTPU that dispatch a widget’s callbacks to the layered application 


¢ Application-level callback programs or learn sequences—Layered 
application code that is executed after VAXTPU has received a callback 
from a widget 


At the callable interface level, VAXTPU has several callback routines, one 
of which may be called by a widget when an event occurs. An event is a 
user action or other occurrence that affects a widget. Note that although 
DECwindows allows you to specify a different callback routine for each 
reason that a widget can call back, DECwindows VAXTPU does not 
support this capability. For more information about engine-level callback 
routines, see Section 7.4.1. 


At the application level, an application contains one or more callback 
programs or learn sequences specified with CREATE_WIDGET or SET 
(WIDGET_CALLBACK). VAXTPU executes the program or learn sequence 
when it receives a callback from a widget. For more information about 
application-level callback routines, see Section 7.4.2. 


7.4.1 Callable Interface-Level Callback Routines 


If you are layering an application on VAXTPU or on EVE, you specify 
callable interface-level callback routines only if you are specifying a 
widget’s callback resources in a User Interface Language (UIL) file. 


Callbacks can pass values known as closures, which are strings or 
integers whose function depends on the application you are writing. For 
more information about what closures are and how to use them, see 
Section 7.5. 


You use the VAXTPU callable interface routine TPU$WIDGET_INTEGER_ 
CALLBACK as the callback routine for all callbacks that have an integer 
closure and the VAXTPU routine TPU$WIDGET_STRING_ Sa ia for 
all callbacks that have a string closure. 


Although the SET (WIDGET) built-in allows you to specify values for 
various resources of a widget, there are restrictions on specifying values 
for callback resources of widgets not organized in an XUI Resource 
Manager hierarchy. When a widget is part of an XUI Resource Manager 
hierarchy, do not include callback resource names or values in the array 
you pass to SET (WIDGET). Instead, specify the callback routine in 
the UIL file. When a widget is not part of an XUI Resource Manager 
hierarchy, use the names of the callback resources in the array you pass 
to SET (WIDGET), and specify 0 as the value of each such callback 
resource. VAXTPU automatically substitutes its common callback entry 
point for the 0 value. Note that a widget that is not part of an XUI 
Resource Manager hierarchy calls back only for those reasons specified 
in the widget’s argument list. If a reason is omitted from the list, the 
corresponding event does not cause a callback. 
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Application-Level Callback Programs or Learn Sequences 


When you specify an application-level callback program or learn sequence 
with CREATE_WIDGET or SET (WIDGET_CALLBACK), all widgets 

in the same XUI Resource Manager hierarchy have the same callback 
program or learn sequence. Therefore, the callback program or learn 
sequence must have a mechanism for handling all possible callback 
reasons. 


Using Closures in DECwindows VAXTPU 
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DECwindows allows you to specify a closure value for a widget. 
DECwindows does not define what a closure value is; a closure is 
simply a value that DECwindows understands how to recognize and 
manipulate so that a DECwindows application programmer can use the 
value if needed in the application. For general information about using 
closures in DECwindows, see the VMS DECwindows Guide to Application 
Programming. 


When a widget calls back to the DECwindows application, the callback 
parameters include the closure value assigned to the widget. DECwindows 
allows the application to define the significance and possible values of the 
closure. 


VAXTPU supports closure values of type STRING and INTEGER. Closure 
values are optional for widgets used by applications layered on VAXTPU. 
If you do not specify a closure value, the built-in GET_INFO (WIDGET, 
"callback_parameters", array) returns UNSPECIFIED in the "closure" 
array element. If you create a widget without using a UIL file, the built- 
in GET_INFO (WIDGET, "callback_parameters", array) returns the 
closure you specified as a parameter to CREATE_WIDGET. If you create 
a widget using a UIL file, the built-in GET_INFO (WIDGET, "callback_ 
parameters", array) returns the closure value (if any) defined in the XUI 
Resource Manager. If none is defined, the built-in returns UNSPECIFIED. 


VAXTPU leaves it to the layered application to use the closure resource in 
any way the application programmer wishes. VAXTPU passes through to 
the application any closure value received as part of a callback. 


The DECwindows version of EVE provides an example of how an 
application can use closure values. DECwindows EVE assigns a unique 
closure value to every widget instance that can be created during an EVE 
editing session. Each closure value corresponds to something that EVE 
must do in response to the activation of that particular widget. When 

an event causes VAXTPU to execute EVE’s main callback program, the 
built-in GET_INFO (WIDGET, "callback_parameters", array) returns the 
widget activated, the reason code (the reason the widget is calling back), 
and the closure associated with the particular widget instance. EVE’s 
main callback program contains an array that is indexed with values 
identical to the widget closure values. Each array element contains a 
pointer to the EVE code to be executed in response to the corresponding 
widget’s callback. EVE’s callback program uses the closure value to locate 
the appropriate array index so the correct EVE routine can be executed in 
response to the callback. 
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If your layered application does not use EVE’s callback program, then 
its callback program or learn sequence must have a mechanism for 
determining which widget is calling back and which application code 
should be executed as a result. 


7.6 Specifying Values for Widget Resources in DECwindows VAXTPU 


This section discusses techniques for specifying values for widget 
resources. 


7.6.1. VAXTPU Data Types for Specifying Resource Values 


VAXTPU supports the following data types with which to specify values 
for widget resources: 


e String 
e Array of strings 


e Integer 


VAXTPU converts the value you specify into the data type appropriate 
for the widget resource you are setting. The following table shows 
the relationship between VAXTPU data types for widget resources and 
DECwindows data types for widget resources: 


Table 7-1 Correspondence Between VAXTPU Data Types and 
DECwindows Argument Data Types 


DECwindows Argument Data Type VAXTPU Data Type 
Array of strings Array of strings 
Boolean Integer 
Callback Integer (0) 
Compound string String 
Compound string table Array of strings 
Dimension Integer 

Integer Integer 
Position Integer 

Short Integer 

String String 
Unsigned character Integer 


VAXTPU does not support setting values for resources (such as pixmap, 
colormap, font, icon, and so on) whose data types are not listed in this 
table. 


When you pass an array specifying values for a widget’s resources using 
CREATE_WIDGET or SET (WIDGET), VAXTPU verifies that each array 
index is a string corresponding to a valid resource name for the specified 
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widget. VAXTPU also verifies that the data type of the value you specify 
is valid for the specified resource. 


7.6.2 Specifying a List as a Resource Value 


List box and file selection widgets manipulate lists. For example, the file 
selection widget manipulates a list of files. The widget resource that stores 
such a list is specified to VAXTPU using an array. 


To handle an array that passes a list to a widget, DECwindows must 
know how many elements the array contains. For example, if you, the 
application programmer, set the value of the "item" resource of a list box 
widget to point to a given array, DECwindows does not handle the array 
successfully unless the list box widget’s "itemsCount" resource contains 
the number of elements in the array. 


However, you do not necessarily know how many elements the array has | 
at a given moment. To help you pass arrays, VAXTPU has a convention 
for referring to widget resources. If you follow the convention, VAXTPU 
will handle the resource that stores the number of array elements. The 
following paragraphs discuss the naming convention in more detail. 


When you use the VAXTPU built-in procedure SET (WIDGET) to pass 

a list to a widget, specify both the list name and the list count resource 
in the same array index, separated by a line feed (ASCII (10)). The 
array element should be the array that is to be passed. For example, to 
specify the "items" resource to the list box widget, use code similar to the 
following: 


line feed := ASCII (10); 
resource _array {"items" + line feed + "itemsCount"}:=list_array; 


The line-feed character, ASCII (10), is a delimiter separating two resource 
‘ names. 


VAXTPU automatically generates two resource entries. The first is the 
array of strings specifying the data to the list box for the "items" resource. — 
The second is the count of elements in the array for the "itemsCount" — 
resource. 


To get resource values from a widget, use the following statement: 
GET_INFO (widget, "WIDGET INFO", array) 


The indices of the array parameter are strings or string constants naming 
the resources whose value you want. (The initial values in the array are 
unimportant.) The GET_INFO statement directs VAXTPU to fetch the 
specified resource values of the specified widget and put the values in the 
array. 


For list box widget or file selection widgets, one element of the array 
receives another array containing the list manipulated by the widget. 

When you create the index of the element that receives the widget’s list, 
you must observe the naming convention so that VAXTPU can handle both / 
the list itself and the resource value specifying the length of the list. Give ° 
the index the following format: 
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items<line-feed>items_count 


For example, if you used GET_INFO (widget, "WIDGET_INFO", array) to 
get resource values from a list box widget, you could specify the index for 
the element storing the widget’s list as follows: 


"items" + ASCII(10) + "itemsCount" 


Note that the element for the widget’s list does not actually contain an 
array until after execution of the GET_INFO statement. When VAXTPU 
encounters the GET_INFO statement, it parses the indices of the specified 
array. When VAXTPU parses the index of the element for the widget’s list, 
it fetches both the list itself and the length of the list. Using the resource 
specifying the length, VAXTPU creates an array of the correct size to hold 
the widget’s list. 


7.7 Sample Uses of DECwindows VAXTPU Built-ins 


You can use the DECwindows VAXTPU built-in procedures in many ways. 
However, you may find it useful to look at sample procedures showing 
how other programmers have used some of the DECwindows VAXTPU 
built-ins. Therefore, this section presents a number of procedures using 
DECwindows built-ins. Most of the procedures are drawn from the code 
implementing the Extensible VAX Editor (EVE). Some have been modified 
to make them easier to understand. 


You can see all the code used to implement EVE by looking at the files in 
the directory pointed to by the logical name SYS$EXAMPLES. To see a 
directory of the files available, type the following command from the DCL 
command line: 


$§ DIR SYSSEXAMPLES: EVES* .TPU 


These files contain procedures using almost all of the new and modified 
built-ins. 


7.7.1 ee of Displaying a Dialog Box 


Example 7—1 illustrates one of the ways a layered application can use 
the CONVERT built-in. This procedure is a modified version of the 
EVE procedure eve$$mb2_dispatch. You can find the original version 
in SYS$SEXAMPLES:EVES$MOUSE.TPU. For more information about 
using the files in SYS$EXAMPLES as examples, see Section 7.7. 


The procedure displays EVE’s selection popup menu on the screen if the 
procedure is called while a select range or found range is active. 


This example uses the following global variables and procedures: 


e EVE$CALLBACK_DISPATCH - The procedure that EVE uses to 
dispatch all widget callbacks. 


e EVE$X_FOUND_RANGE - A global variable that holds the range for 
the last text found. If there is not currently a found range, it is set to 
Zero. 
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¢ EVE$X_SELECT_POPUP - A global variable that holds the popup 
menu widget used when a selection is present. 


° EVE$X_SELECT_POPUP_HEIGHT - A global variable that holds the 
height of the selection popup menu. 


¢ EVE$X_SELECT_POPUP_WIDTH - A global variable that holds the 
width of the selection popup menu. 


e EVE$X_SELECT_POSITION - A global variable that holds the start 
marker for the select range. If there is not currently a selection, it is 
set to zero. 


Example 7-1 EVE Procedure Displaying a Selection Dialog Box 


PROCEDURE eveS$$mb2_ dispatch 


local status, 
the window, 
temp array, 
the widget, 
x 1, 
XZy 
widget hierarchy, 
y_l, 
y_2; 


@ IF (LOCATE MOUSE (the window, x1, y_1) <> 0) 


THEN 
2 CONVERT (the window, CHARACTERS, x1, y_1, 
DECW_ROOT WINDOW, COORDINATES, 
x2, y_2); 
IF (eve$x_select position <> 0) OR ! A selection exists 
(eve$x_found_range <> 0) ! A found range exists 
THEN 
Ir GET INFO (eveSx select popup, "type") <> WIDGET 
THEN 
3 widget hierarchy := SET (DRM HIERARCHY, “EVESWIDGETS") ; 
eveSx select popup := CREATE WIDGET ("SELECT POPUP", 
widget hierarchy, 
SCREEN, 
"eveScallback dispatch") ; 
ENDIF; 
! Get width and height of this pop-up menu if needed 
4 temp array := CREATE ARRAY; 
temp_array {eveSdwt$c_ width} := 0; 
temp_array {eveSdwt$c_ height} := 0; 
status := GET INFO (eveSx select _popup, “WIDGET INFO", temp_array); 
eve$x_ select popup width := temp array {eveSdwt$c_ width}; 
eve$x_select_popup_ height := temp _array {eveSdwt$c_height}; 


(continued on next page) 
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Example 7-1 (Cont.) EVE Procedure Displaying a Selection Dialog Box 


! Calculate position for upper left corner of 
! dialog box and set the appropriate resources of the widget 


temp array 


>= CREATE ARRAY; 


temp array {eveS$dwt$c nx} := X2 - (eve$x_ select popup width/2); 
IF temp_array {eveSdwt$c nx} < 1 


THEN 


temp array {eveSdwt$c_ nx} := 1; 


ENDIE-? 


temp _array {eveSdwt$c_ ny} := 
IF temp _array {eveSdwt$c_ ny} 


THEN 


y 2 - (eve$x_ select popup height/2) ; 
aL 


temp array {eveSdwt$c_ ny} := 1; 


ENDIF; 


SET (WIDGET, eve$x_select_ popup, temp array); 
MANAGE WIDGET (eveS$x_ select popup); 


ENDIF; 
ENDIF; 
RETURN (TRUE) ; 


ENDPROCEDURE; 


@ The return value from the LOCATE_MOUSE built-in procedure 


indicates whether the pointer cursor is in the window. LOCATE_ 
MOUSE also returns the row, column, and window where the pointer 
cursor is located. The coordinates returned refer to a system whose 
origin is in the upper left corner of the VAXTPU window. 


This clause converts the pointer cursor location from a system whose 
origin is at the upper left corner of the VAXTPU window to a system 
whose origin is at the upper left corner of the DECwindows root 
window. For more information about the difference between VAXTPU 
windows and DECwindows windows, see Chapter 6. 


SET (DRM_HIERACHY, file_spec) allows you to tell VAXTPU which 
XUI Resource Manager hierarchy to use. An XUI Resource Manager 
hierarchy is a set of widgets implementing a user interface. For 
example, EVE’s menu bar and menu widgets compose an XUI Resource 
Manager hierarchy. 


EVE uses the XUI Resource Manager hierarchy stored in the file 
EVE$WIDGETS.UID. If you are extending EVE, you need not set the 
hierarchy again. 2 


VAXTPU allows you to use multiple XUI Resource Manager 
hierarchies. If you want to use a second hierarchy (defined in a file 
other than EVE$WIDGETS.UID), use the SET (DRM_HIERARCHY) 
statement before using the CREATE_WIDGET statement. 


GET_INFO (widget, "widget_info", array) allows you to fetch 
information about a widget. The index of each element of the array 
must be a string naming the resource whose value you want to fetch. 
For more information about what resources a given widget supports, 
see VMS DECwindows Toolkit Routines Reference Manual. 


(continued on next page) 
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Example 7-1 (Cont.) EVE Procedure Displaying a Selection Dialog Box 


© SET (WIDGET, widget, array) allows you to set a widget’s resource 
values. The index of each element of the array must be a string 
naming the resource whose values you want to set. For more 
information about what resources a given widget supports, see VMS 
DECwindows Toolkit Routines Reference Manual. 


© MANAGE_WIDGET realizes the widget and makes it visible on the 
screen. 


Example of Creating a “Mouse Pad” 


Example 7-2 shows how to use the variant of CREATE_WIDGET that calls 
the XUI Toolkit low-level creation routine. The module in Example 7-2 
creates a screen representation of a keypad. Instead of pressing a keypad 
key, a user can click on the widget representing the key. 


Example 7-2 Procedure Creating a “Mouse Pad” 


! SAMPLE .TPU 
++ 
Table of Contents 
SAMPLE .TPU 
Procedure name Description 


oe ee en RD cE oS oe eee Gem aim en ame ee ones oe ae a ee ee ee ee om me eee coe 


! 

! 

! 

I 

! 

! 

! 

! 

! sample sample module ident Ident. 
! sample sample module init Initializes the module. 
I 

! 

! 

! 

! 

I 

! 

! 


eve_ mouse pad Implements the user command DISPLAY MOUSE PAD. 
sample key def Creates a mouse pad "key" push button. 

sample key dispatch Handles push button widget callbacks. 

sample row to pix Converts a row number to pixels. 

sample col to pix Converts a column number to pixels. 

sample key height ) Converts Y dimension from rows to pixels. 
sample key width Converts X dimension from columns to pixels. 


(continued on next page) 
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Example 7-2 (Cont.) Procedure Creating a “Mouse Pad” 


This module layers a "mouse pad" on top of VAXTPU. The mouse pad 
is implemented by creating a dialog box widget that is the parent of a group 
of push button widgets depicting keypad "keys." The resulting 
“mouse pad" is a screen representation of a keypad. The user can 
click on a push button to execute the same function that would be 
executed by pressing the corresponding keypad key. The module uses 
the key map list mapped to the current buffer to determine what 
code to execute when the user clicks on a given push button. To 
use a different key map, substitute a string naming the desired 
key map for the null string assigned to "sample_k_keymap". 

This module can be used with the EVE section file 

Or with a non-EVE section file. 


This module uses the variant of CREATE WIDGET that calls the XUI 
Toolkit low-level creation routine. 


PROCEDURE sample sample module ident ! This procedure returns 
RETURN "V0O1-001"; ' the Ident. 
ENDPROCEDURE,; 

PROCEDURE sample sample module init ! Module initialization. 
ENDPROCEDURE; 


! VAXTPU Declarations for KUI Toolkit constants 


! Use these constants as arguments to the DEFINE WIDGET built-in. 
! The strings are the symbols that evaluate to the 
! widget class records for the DECwindows widgets. 


CONSTANT 

sample _k labelwidgetclass := "labelwidgetclassrec", 

sample k dialogwidgetclass := "dialogwidgetclassrec", 

sample _ k push-buttonwidgetclass := "pushbuttonwidgetclassrec"; 
! Use these constants, which are XUI Toolkit 
! resource name strings, as callback reasons, resource values, or 
! arguments to the CREATE WIDGET built-in. 

CONSTANT 

sample _k cstyle := "style", 

sample _k modeless := 2, 

sample k nunits := “units", 

sample k pixelunits := 1, 

Sample k ntitle: += "titie™, 

sample k nx := "x", 

sample k ny := "y", 

sample k nheight := "height", 

sample _k nwidth := "width", 

sample k nlabel := "label", 

sample kt_nactivate callback := "activateCallback", 

sample kt_nborderwidth := "borderWidth", 

sample kt nconformToText := "conformToText", 

sample _k cractivate := 10; 


! These constants are intended for use only in this sample module 
! because their values are specific to the mouse pad application. 


(continued on next page) 
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Example 7-2 (Cont.) Procedure Creating a “Mouse Pad” 


CONSTANT 
sample k x pos := 500, ! Screen position for mouse pad. 
sample k x pos := 500, 
sample k keypad border := 5, ! Width of border between keys and edge. 
sample k key height := 30, ! Key dimensions. 
sample _k key width := 60, 
sample _ k button border frac := 3, ! Determines spacing between keys. 
sample _k overall height := (sample _k_ key height * 5) 
+ ((sample k key height 
/ sample _k button border frac) * 5) 
+ sample k keypad border, 
sample k overall width := (sample _k key width * 4) 
+ ((sample_k key width 
/ sample _k button_border frac) * 4) 
+ sample k keypad border, 
sample k_ keymap := ’’, ! If this constant has a null string 
! as its value, the program uses the 
! current key map list to determine what 
! code to execute when the user 
! clicks on a given push button. 
sample_k pad title := "Sample mouse pad", ! Title of the mouse pad. 
sample_k closure := ’’; ! Not currently used. 
PROCEDURE eve_mouse_pad ! Implements the EVE user command MOUSE PAD. 
ON _ ERROR 


[TPUS CONTROLC] : 
eveSlearn_abort; 
ABORT; 
ENDON_ERROR 


! Checks whether the dialog box widget class has already been defined. 
! If not, defines the dialog box widget class and creates a widget 
! instance to be used as the "container" for the mouse pad. 


IF GET_INFO (sample x dialog class, ‘type’) <> INTEGER 
THEN 
sample x dialog _ class 
>= DEFINE WIDGET CLASS (sample k_ dialogwidgetclass, 
"dwtS$dialog box popup create"); 
ENDIF; _ 


@ sample x keypad >= CREATE WIDGET (sample _ x dialog class, "Keypad", SCREEN, 


"MESSAGE (’ CALLBACK activated’)", 
"sample k closure ", 

sample k cstyle, sample _k modeless, 
sample _k nunits, sample k pixelunits, 
sample _k ntitle, sample k pad_title, 
sample k nheight, sample k overall height, 
sample _k nwidth, sample _k overall width, 
sample k nx, sample k x pos, 

sample _k_ ny, sample_k_y pos); 


! Checks whether the push-button widget class has already been defined 
! and, if not, defines the class. 


(continued on next page) 
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Example 7-2 (Cont.) Procedure Creating a ‘Mouse Pad” 


IF GET INFO (sample x pushbutton _ class, ‘type’) <> INTEGER 
THEN 

sample x pushbutton_class ! 
DEFINE WIDGET CLASS (sample _k pushbuttonwidgetclass, ! 


"dwtSpush button_create") ; 


This statement 
using the built_in 
DEFINE WIDGET CLASS 
defines the 

class of the 

push button 

widgets 


ENDIF; 


ome eee ee 


! Initializes the array that the program passes repeatedly 
| to-ahe ‘procedure. “sample key der”. 


sample x attributes CREATE ARRAY; 

sample x _ attributes {sample k nactivate callback} 
sample x_ attributes {sample_k_nborderwidth} 2; 
sample x pad program COMPILE ("sample key dispatch"); 


OF 


! Creates and manages all of the "keys" in the mouse pad. The procedure 
! "sample key def" returns a variable of type widget, so you can use the 
' returned value as an argument to the built-in MANAGE WIDGET. 


© MANAGE WIDGET (sample key def ("PF1", O, 0, 1, 1, sample x pad program), 
sample key def ("PF2", 1, 0, 1, 1, sample x pad program), 
sample: key def ("PES", 2, OO, 1) dy, Sample. = pad. program), 
sample key def ({("PF4", 3, 0, 1, J, ‘sample x pad program) , 
sample key def ("KP7", 0, 1, 1, 1, Sample x pad program) , 
sample. key def ("KPS™, 1, 1, 1d, 1, sample x pad program), 
sample key def ("KPO" 2; 1, 1y-dy. sample. « pad -program).,; 
sample key def ("-", 3, 1, 1, 1, sample _x pad program, “minus"), 
sample key def ("KP4", 0, 2, 1, 1, sample x pad program), 
sample key def ("KP5", 1, 2, 1, 1, sample_x pad program), 
sample. key def (“"KP6", 2, 2; 1, 1) sample .x pad program). 
sample key def (",", 3, 2, 1, 1, sample_x pad program, "comma"), 
sample _ key def ("KP1", 0, 3, 1, 1, sample x pad program), 
sample key def {"KP2™, 1, 3, 1, 1, sample = -pad program); 
sample key deft ("KP3", 2, 3, 1, 1, sample x pad program), 
sample key def ("Enter", 3, 3, 2, 1, sample _x pad program, 

"enter"), 
sample key def ("KPO", QO, 4, 1, 2, sample x pad program), 
sample key def (".", 2, 4, 1, 1, sample x pad program, 
"period")); 
sample x shift was last := FALSE; ! The program starts out assuming that 


' no GOLD key has been pressed. 


@ MANAGE WIDGET (sample x keypad); ! This statement displays the 


! resulting mouse pad. 


RETURN (TRUE) ; 
ENDPROCEDURE ! End of procedure eve_mouse pad. 


PROCEDURE sample key def ! Creates a mouse pad "key" push-button 
! widget. 
(the legend, ! What characters to show on the push-button label. 


! Location of the key in relation to the parent 
! widget’s upper left corner. 


the row, the col, 


(continued on next page) 
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the width, the_height, ! Dimensions of the key. 


the pgm; ! Program to use as the callback routine; used 
! as a parameter to the CREATE WIDGET built-in. 


the string); ! The string representation of the name 

! of a key if the key name is not going 

! to be the same as the legend (as in 

! the case of the comma). Specify the null 
! string if the key name and the legend are 
I 


the same. 


IF GET_INFO (the string, ‘’type’) = UNSPECIFIED 
THEN 
the string := the_legend; ! Determines whether the optional parameter 
! the string is provided. 
ENDIF; 


RETURN CREATE WIDGET (sample_k pushbutton_class, "Key", sample _x_ keypad, 
the pgm, 
(sample _k_keymap + ’ ’ + the string), 
sample x attributes, 
sample kt_nconformToText, 0, 
sample k nlabel, the legend, 
sample k nheight, sample key height (the width), 
sample k nwidth, sample key width (the height), 
sample _k_ nx, sample _col_to pix (the_row), 
sample k_ nx, sample _row_to_ pix (the_col)); 


ENDPROCEDURE ! End of the procedure "sample key def". 


PROCEDURE sample key dispatch ! Handles push-button widget callbacks. 


LOCAL status, ! Variable to contain the return value from 
! GET INFO (WIDGET, "callback_parameters",). 


blank index, ! Position of the blank space in the tag string. 
temp array, ! Holds callback parameters. 
a_ shift key, | The SHIFT key in the current key map list. 
the_key, ! A string naming a key. 
gold_key; ! Name.oe the GOLD key. 

ON_ERROR 


[TPUS CONTROLC] : 
eveSlearn_ abort; 
ABORT; 
ENDON_ERROR 


@ status >= GET INFO (widget, "callback parameters", temp_array); 
Swidget := temp_array {’widget’ }; 
Swidget_tag := temp_array {’closure’ }; 
Swidget_reason := temp_array {’reason_code’ }; 

@ the key >= EXECUTE ("RETURN (KEY NAME (" + Swidget_tag Saas ee lass 


gold_key := GET _ INFO (eveScurrent_key map_list, "shift_key"); 
IF the key = gold _ key 
THEN 

sample shift_was last := TRUE; ! User pressed Gold Key 


(continued on next page) 
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ELSE 


IF sample shift was last 
THEN 

the key := KEY NAME (the key, SHIFT KEY); 
ENDIF; 


CASE $widget_reason 
[sample kt _cractivate]: 
EXECUTE (the key); 


[OTHERWISE] : 
eve show _key (the key) 
ENDCASE; 
sample shift _was_last := FALSE; 
ENDIF; 
RETURN; 


ENDPROCEDURE ! End of the procedure "sample key dispatch". 


! These procedures implement position and 
! size calculations for the push-button widgets. 


PROCEDURE sample row_to pix (row) ! Converts a row number to the 
! pixel-based measuring system. 
RETURN sample k keypad border + 
(row * (sample _k key height + (sample_k_ key height 
/ sample k button border frac))); 


ENDPROCEDURE ! End of the procedure "sample row _ to pix". 


PROCEDURE sample col _to pix (col) ! Converts a column number to the 
! pixel-based measuring system. 
RETURN sample k_ keypad border + 
(col * ((sample kt_key width + sample kt_key width) 
/ sample kt button_border frac )); 


ENDPROCEDURE ! End of the procedure "sample col to pix". 


PROCEDURE sample key height (given _height) ! Converts the Y dimension 
! from rows to pixels. 
IF given_height = 1 
THEN 
RETURN sample k_ key height; 
ELSE 
RETURN ((sample k key height * given_height) 
+ (sample _k key height / sample _k button _border frac) 
* (given height - 1)); 
ENDIF; 
ENDPROCEDURE ! End of the procedure "sample _ key height". 


PROCEDURE sample key width (given_width) ! Converts the X dimension 
! from rows to pixels. 
IF given_width = 1 
THEN 
RETURN sample _k key width; 
ELSE 
RETURN ((sample_k_ key width * given width) 
+ (sample_k key width / sample_k button_border frac) 
* (given_width - 1)); 
ENDIF; 
ENDPROCEDURE ! End of the procedure "sample key width". 


(continued on next page) 
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@ When you create widgets directly in VAXTPU (that is, without using 
the XUI Resource Manager to manipulate widgets defined in a UIL 
file) you must define each class of widget. For example, a widget 
can belong to the class of push button widgets, dialog box widgets, 
menu widgets, or another similar class. The DEFINE_WIDGET_ 
CLASS built-in procedure tells VAXTPU the widget class record name 
and creation entry point for the class of widget. DEFINE_WIDGET_ 
CLASS also returns a widget id for that widget class. Define a widget 
class for each class of widget only once in a VAXTPU session. 


@ The CREATE_WIDGET built-in allows you to create an instance of a 


widget for which you have a widget id. An instance is one occurrence 
of a widget of a given class. For example, EVE has many menu 
widgets, each of which is an instance of a menu widget. 


This example creates a dialog box widget to contain the mouse pad. 


© Each of the keys of the mouse pad is managed. However, they do not 
become visible until their parent, the dialog box widget in variable 
SAMPLE_X_ KEYPAD, is managed. 


@ Managing a widget whose parent is visible causes that widget and all 


its managed children to become visible. 


© GET_INFO (WIDGET, "callback_parameters", array) returns the 
callback information in the array parameter. For more information 
about using this built-in, see the built-in’s description in Chapter 5. 


@ When each key widget of the mouse pad was created, the closure 
value for the widget was set to be the string corresponding to the 
name of the key that the widget represents. This statement uses the 
EXECUTE built-in to translate the string into a key name. 


7./.3 Example of Implementing an EDT-Style APPEND Command 
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Example 7-3 shows one of the ways an application can use the GET_ 
CLIPBOARD built-in. This procedure is a modified version of the 

EVE procedure eve$edt_append. You can find the original version in 
SYS$EXAMPLES:EVE$EDT.TPU. For more information about using the 
files in SYS$EXAMPLES as examples, see Section 7.7. 


The procedure eve$edt_append appends the currently selected text to the 
contents of the clipboard if the user has activated the clipboard; otherwise, 
the procedure appends the current selection to the contents of the Insert 
Here buffer. 


This example uses the following global variables and procedures from 
EVE: 


e EVE$MESSAGE - A procedure that translates the specified message 
code into text and displays the text in the message buffer. 
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EVE$$RESTORE_POSITION - A procedure that repositions the 
editing point to the location indicated by the specified window and 
marker. This procedure is for EVE internal use only. Do not call this 
procedure in a user-written procedure. 


EVE$LEARN_ABORT - A procedure that aborts a learn sequence. 


EVE$SELECTION - A procedure that returns a range containing the 
current selection. This can be the select range, the found range, or the 
text of the global selection. 


EVE$$TEST_IF_ MODIFIABLE - A procedure that checks whether a 
buffer can be modified. This procedure is for EVE internal use only. 
Do not call this procedure in a user-written procedure. 


EVE$X_DECWINDOWS_ACTIVE - A Boolean global variable that is 
true if VAXTPU is using the DECwindows screen manager. If VAXTPU 
is not using the DECwindows screen manager, the DECwindows 
features are not available. 


EVE$$X_STATE_ARRAY - A global variable of type ARRAY describing 
various EVE flags and data. This variable is private to EVE and 
should not be used by user routines. 


EVE$$EDT_APPEND._ PASTE - Procedure which appends text to the 
Insert Here buffer. This procedure is for EVE internal use only. Do 
not call this procedure in a user-written procedure. 


Example 7-3 EVE Procedure Implementing a Variant of the EDT APPEND Command 


PROCEDURE eveSedt_ append 


LOCAL saved mark, 


remove range, 
Oold-string, 


new string, 


remove status; 


ON ERROR 


! Implements EVE’s version of 
! the EDT APPEND command. 


! Marks the editing point at the 

! beginning of the procedure. 

! Stores the currently selected text. 

! Stores the text that was in the clipboard. 


! Stores the old contents of the clipboard 
! plus the currently selected text. 


! Indicates whether the selected text 
! should be removed. 


[TPUS CLIPBOARDNODATA] : 
eveSmessage (EVES NOINSUSESEL) ; 
eveS$restore position (saved mark); 


eveSlearn abort; 
RETURN (FALSE) ; 


[TPUS CLIPBOARDLOCKED] : 
eveSmessage (EVES CLIPBDREADLOCKR) ; 
eve$$restore position (saved_mark) ; 


eveSlearn abort; 
RETURN (FALSE) ; 


(continued on next page) 


7-19 


© 6 


Programming in DECwindows VAXTPU 
7.7 Sample Uses of DECwindows VAXTPU Built-Ins 


Example 7-3 (Cont.) EVE Procedure Implementing a Variant of the EDT APPEND Command 


[TPUS CONTROLC] : 
eveSSrestore position (saved_mark); 
eveSlearn.abort; 
ABORT; 
[OTHERWISE] : eveSSrestore position (saved_mark); 
eveSlearn_abort; 
ENDON_ERROR; 


remove range := eve$selection (TRUE) ; 
IF remove_range <> 0 
THEN 
saved_mark := MARK (NONE) ; 
remove _ status := eveStest_if modifiable (GET_INFO (saved_mark, "buffer")); 
IF eve$x decwindows active 
THEN 
IF eveS$x_state_array {eve$$k_ clipboard} 
THEN 
old _ string := GET CLIPBOARD; 
string range := old_string + str (remove_range); 
WRITE CLIPBOARD ("", new_string); 
IF remove status 
THEN 
ERASE (remove_range) ; 
eveSmessage (EVES REMCLIPBOARD) ; 
ENDIF; 
ELSE 
eveSSedt_append_paste (remove_range, remove status); 
ENDIF; 
ELSE 
eveS$edt_append_paste (remove_range, remove status); 
ENDIF; 
POSITION (saved_mark) ; 
remove _range := 0; 
RETURN (TRUE) ; 
ENDIF; 


eveSlearn_ abort; 
RETURN (FALSE) ; 


ENDPROCEDURE; 
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@ The GET_CLIPBOARD built-in procedure returns a copy of the text 
stored in the clipboard. Only data of type STRING can be retrieved 
from the clipboard. Any other data causes VAXTPU to signal an error. 


@® The WRITE_CLIPBOARD built-in procedure stores data in the 
clipboard. The first parameter allows you to specify the label for 
this data. However, in this release the clipboard supports only one 
entry at a time, so you can use any string for the first parameter. 
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7.7.4 Example of Testing and Returning a Select Range 


The code fragment in Example 7-4 shows how a layered application 

can use GET_GLOBAL SELECT. This code fragment is a portion of 

the EVE procedure eve$selection. You can find the original version in 
SYS$EXAMPLES:EVE$CORE.TPU. For more information about using the 
files in SYS$EXAMPLES as examples, see Section 7.7. 


The procedure eve$selection returns a select range, found range, or global 
selection for use with EVE commands that operate on the select range. 


This example uses the following global variables and procedures from 
EVE: 


e EVE$MESSAGE - A procedure that translates the specified message 
code into text and displays the text in the message buffer. 


e EVE$LEARN_ABORT - A procedure that aborts a learn sequence. 


¢ EVE$X_DECWINDOWS_ACTIVE - A Boolean global variable that is 
true if VAXTPU is using the DECwindows screen manager. If VAXTPU 
is not using the DECwindows screen manager, the DECwindows 
features are not available. 


Example 7-4 EVE Procedure Returning a Select Range 


PROCEDURE eveSselection ( 
do _ messages; ! Display error messages? 
found _range arg, ! Use found range? (D=TRUE). 
global arg, ! Use global select? (D=FALSE) . 
nuli range arg, ! Extend null ranges? (D=TRUE). 
cancel arg) ! Cancel selection? (D=TRUB). 


! Return Values: range The selected range. 

! 0 There was no select range. 

! NONE There was a null range and 

' null _range_arg is FALSE. 

! string Text of the global selection 


if. VGlobal. arg’ as: ‘TRUE. 


LOCAL possible selection, 
use found_range, 
use global, 
extend null range, 
cancel range; 


ON ERROR 
[TPUS SELRANGEZERO] : 
[TPUS GBLSELOWNER] : 
eveSmessage (EVES NOSELECT) ; 
eveSlearn_ abort; 
RETURN (FALSE) ; 
[OTHERWISE] : 
ENDON_ ERROR; 


(continued on next page) 
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Example 7-4 (Cont.) EVE Procedure Returning a Select Range 


The procedure first tests whether it 
has received a parameter directing 

it to return a found range or global 
selection if no select range has been 
created by the user. 


IF GET INFO (found_range_arg, "type") = INTEGER 


THEN 
use found_range := found range arg; 
ELSE 
use _found_range := TRUE; 
ENDIF; 
IF GET INFO (global arg, "type") = INTEGER 
THEN 7 
use global := global arg; 
ELSE 
use Global. := FALSE; 
ENDIF; 


In the code omitted from this example, 
eveSselection returns the appropriate 
range if the calling procedure has 
requested the user’s select range 

or a found range. 


ee ee ee eee 


If there is no found range or select 
range, the procedure returns 

the primary global selection 

1f it exists. 


IF use_ global and eve$x_ decwindows_ active 


THEN 
possible selection := GET GLOBAL SELECT (PRIMARY, 
"STRING" ) ; 
IF GET INFO (possible selection, "type") = STRING 
THEN 
RETURN (possible selection) ; 
ENDIF; | 
ENDIF; 
RETURN (0); ! Indicates failure. 
ENDPROCEDURE; 


@ DECwindows allows you to designate more than one global selection. 
The two most common global selections are the primary and secondary 


(continued on next page) 
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Example 7-4 (Cont.) EVE Procedure Returning a Select Range 


selections. A global selection can be owned by only one DECwindows 
application at a time. 


The GET_GLOBAL_SELECT built-in returns the data for the 
requested selection in the requested format. If the requested selection 
is not currently owned by any application, or if the owner cannot 
return it in the requested format, then GET_GLOBAL_ SELECT 
returns UNSPECIFIED. 


If the selected information contains multiple records, the records are 
separated by the line feed symbol (ASCII (10)). 


7.7.5 Example of Resizing Windows 


Example 7-5 shows a procedure sample_new_screen_size, which 
manipulates visible windows when the user makes the screen smaller. 

It removes visible VAXTPU windows from the screen, starting at the 
bottom of the VAXTPU screen, until the combined length of the remaining 
windows is less than or equal to the new, smaller screen size or until 
there is only one window left. (For more information about the difference 
between VAXTPU windows and DECwindows windows, see Chapter 6.) 

If only one window remains, the procedure adjusts the window to fit the 
screen. If two or more windows remain, the procedure adjusts the current 
window and the bottom window. 


The procedure uses the following variants of the built-in GET_INFO 
(window_variable): 


¢ GET_INFO (window_variable, "bottom") 
¢ GET_INFO (window_variable, "length") 
e GET_INFO (window_variable, "top") 


This example uses the following global variables and procedure from EVE: 


e EVE$GET_WINDOW - A procedure that returns the window 
associated with a number. The windows are numbered sequentially, 
from top to bottom. 


e EVE$X_NUMBER_OF_WINDOWS - A global variable that holds the 
count of the visible windows. 


° EVE$$GET_WINDOW_NUMBER - A procedure that returns a number 
for the current window. EVE associates a value with each window so 
EVE can save information about specific windows. This procedure is 
for EVE internal use only. Do not call this procedure in a user-written 
procedure. 
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e EVE$$REMOVE_WINDOW - A procedure that removes a window 
from the screen. This procedure is for EVE internal use omy. Do not 
call this procedure in a user-written procedure. 


Example 7-5 Procedure Resizing Windows 


PROCEDURE sample new_screen size 


LOCAL overhead, 
new_ screen length, 
number, 
the count, 
total length, 
some window, 
a_window, 
new _ top, 
a_length, 
Cop. 2d usc, 
bottom _window, 
bottom adjust; 


overhead := 2; ! This provides lines for the command window and message 
! window, assuming each window has a length of 1. 
@ new screen length >= get_info (SCREEN, "new length"); 
number := eve$$get_window_ number; i This sets: “number” Lo. be 


! the number of the current window. 


the count := eveSx_number_of windows; i Thus seus -"Ehe -counk™ Lo 
1 be: the ‘total. number “or 
! visible windows. 


! The following lines determine the combined lengths of all 
! user-created windows visible on the screen, plus the lengths of the 
! command window and message window. 


total length := overhead; 
the count := eve$x_number of windows; 
LOOP 
BATTER che count < i; 
some_window >= eveSget | window (the count); 


' "Some_window" is the bottom-most window not yet measured. 


total length := total length + 
2) GET INFO (some_window, "length", WINDOW) ; 


the: count: <= The count = 2; 


ENDLOOP; 


(continued on next page) 
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7-5 (Cont.) Procedure Resizing Windows 


the coun 

LOOP 
EXT? 
a wi 


IF n 


THEN 


ENDI 


LE on 


THEN 


! The following statements delete windows from the screen, starting 
! with the bottom-most window, until the sum of the lengths 

! of all remaining windows is less than or equal to the new screen 
{ length. 

t := eveSx number of windows; 


IF the count <= 1; 

ndow := eveSget window (the count); ! This statement sets "a window" to 
' to be the bottom-most 
! window not yet examined 
! in this loop. 


umber > the count 

new top := GET INFO (a_window, "top", WINDOW) ; 

EB; 

umber <> the count ! If the current window is still 
! above the window to which you’re 
! presently comparing it 

a_length := GET INFO (a _ window, "length", WINDOW) ; 


! The following clause prevents the loop from deleting 
! the bottom window if the new screen length 
! is greater than or equal to the old screen length. 


iF new screen length. < total..léength 


! The following statement decreases "total length" by the length 
! of the window presently being examined. 


THEN 
total. tength.<.= tocal length — -a.léngen; 


! The following statement removes the window 
! presently being examined. 


eveS$Sremove window (the count); 


ENDIF; 


EXITIF total length <= new screen length; 


ENDIF; 
the count := the count - 1; ! Next time through the loop, the window 
! being examined will be the window 
! just above the window examined this time. 
ENDLOOP ; 
IF eve$x number of windows = 1 
THEN 
adjust window (CURRENT WINDOW, 


KLSE 


1 - get_info (CURRENT WINDOW, "top", WINDOW), 
néw. screen lengihn =overhead 


-~get_ info (CURRENT WINDOW, "bottom", WINDOW) ); 


(continued on next page) 
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Example 7-5 (Cont.) Procedure Resizing Windows 


! The following statements adjust the top of the current 
! window and the bottom of the bottom window, if needed, 
! to occupy the space left by deleting windows. 


IF new_top <> 0 
THEN 
top_adjust := new_top - GET_INFO (CURRENT WINDOW, 
"top", WINDOW) ; 
ADJUST_WINDOW (CURRENT_WINDOW, top_adjust, 0); 


ENDIF; 
bottom window := eveSget window (eve$x_ number of windows) ; 
bottom_adjust := new_screen_length - 

overhead - 


! This statement using 
! GET INFO (window, "“bottom") 
! calculates the amount 


GET INFO (bottom window, ! 
| 
l 
! by which to adjust the 
l 
1 


"bottom", WINDOW) ; 


! bottom of the bottom 
! window. 


ADJUST WINDOW (bottom _ window, 0, bottom_adjust) ; 
ENDIF; 


ENDPROCEDURE; 


GET_INFO (SCREEN "new_length") returns the size of the screen 
after a resize occurs. 


GET_INFO (window, "length", WINDOW) returns the length of the 
window. | 


Number is greater than the_count only when the current window is 
below the window to which you are comparing it. 


GET_INFO (window, "top", WINDOW) returns the top line of the 
window. 


GET_INFO (window, "bottom", WINDOW) returns the line number of 
the last line in the window. 


eo 6 © 8&8 8S 


7.7.6 Example of Unmapping Saved Windows 


Example 7-6 shows a procedure sample_save_window_info_and_unmap, 
which saves information about all visible VAXTPU windows in the array 
window_array and then unmaps all visible VAXTPU windows. The 
windows can be reconstructed later using the information in window_ 
array. 


The procedure uses the following variants of the built-in GET_INFO 
(window_variable): 


e GET_INFO (window_variable, "width") 
e¢ GET_INFO (window_variable, "key_map_list") 
e GET_INFO (window_variable, "scroll_bar", VERTICAL) 
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¢ GET_INFO (window_variable, "scroll_bar_auto_thumb", VERTICAL) 


Note: DIGITAL does not guarantee that this example will work 
successfully with future versions of EVE. 


Example 7-6 EVE Procedure Unmapping Saved Windows 


PROCEDURE sample save _window_info and_unmap (; window_array) 


LOCAL the: count, 
the window, 
saved buffer, 
the row, 
temp; 


ON ERROR 
[TPUS CONTROLC] : 
LP GHEY INFO (saved buffer, “type”) = -BUFFER 
THEN 
eveSmessage (EVES REBLDWINDOWS) ; 
eveSsetup windows (saved buffer); 
eveSmessage (EVES WINDOWSREBLT) ; 
UPDATE (ALL); 
ENDIF; 
eveSlearn_abort; 
ABORT; 
[OTHERWISE]: 
ENDON_ERROR; 


the count := 0; 
the window := GET_INFO (WINDOWS, "first"); 
LOOP 

EXITIF the window = 0; 

IF GET INFO (the window, “buffer") <> 0 


THEN 
the count := the count + 1; 

ENDIF; 

the window := GET INFO (WINDOWS, “next"); 
ENDLOOP ; 
window_array := CREATE ARRAY (the count + 1, 0); 
window_array {0} := eve$x number of windows; 
the window := eveSmain window; 
IF GET INFO (the window, "type") = WINDOW 
THEN 

saved _ buffer := GET_INFO (the window, “buffer"); 
ENDIF; 


(continued on next page) 
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Example 7-6 (Cont.) EVE Procedure Unmapping Saved Windows 


LOOP 
EXITLE the count. = ‘0; 
the window := CURRENT WINDOW; 
EXITIF the window = 0; 


temp := CREATE ARRAY (29); 
temp {1} := the window; 
temp {2} := GET INFO (the window, “buffer"); 
temp {3} := GET INFO (the window, "top", WINDOW) ; 
temp {4} := GET_INFO (the window, "length", WINDOW) ; 
temp {8} := get_info (the window, "status_line"); 
IF temp {8} <> 0 
THEN | 
temp {5} := ON; 
BRLSE 
temp {5} := OFF; 
ENDIF; 


POSITION (the window) ; 


temp {6} := MARK (FREE CURSOR); 
the row := GET INFO (the window, "current row"); 
IF the_row = 0 
THEN 

the row := temp {3}; 
ENDIF; 
temp {/} s= the row + 1 - temp {3}; 
temp {9} := GET_INFO (the window, "width"); ! This statement uses 

! GET INFO (window, "width"). 

temp’ {10} 2=-GET INFO: {the window, “scroll. top"); 
temp {11} := GET_INFO (the window, "scroll bottom") ; 
temp {12} := GET_INFO (the window, "scroll amount"); 
temp {13} %= GET INFO (che window, "text")+ 
temp {14} := GET_INFO (the window, "blink video"); 
temp {15} := GET INFO (the window, "blink status"); 
temp {16} := GET INFO (the window, "bold video"); 
temp {1/7} += GET INFO (the. window, “bold status"); 
temp {18} := GET_INFO (the window, "reverse video"); 
temp {19} := GET INFO (the window, “reverse status™) ; 
temp {20} := GET _ INFO (the window, “underline video"); 
temp {21} := GET_INFO (the window, “underline status"); 
temp {22} := GET INFO (the window, “special graphics status"); 
IF GET INFO (the window, "pad") 
THEN 

temp {23} := ON; 
BLSE 

temp {23} := OFF; 
ENDIF; 
temp {24} := GET INFO (the window, 

"shitt.amount™); 

temp {25} := GET_INFO (the window, ! This statement uses 
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(continued on next page) 


Tf 


Programming in DECwindows VAXTPU 
7.7 Sample Uses of DECwindows VAXTPU Built-ins 


Example 7-6 (Cont.) EVE Procedure Unmapping Saved Windows 


IF GET INFO (SCREEN, "decwindows") 
THEN 
temp {26} := (GET INFO (the window, ! 


This statement uses 


"seroll bar", ! GET INFO (window, “scroll bar"). 


VERTICAL) <> 0); 


IF temp {26} 


! If the vertical 
' scroll bar is 

! on, save the 

! TnHtormat lon. 


THEN 
temp {27} := GET_INFO (the window, ! This statement uses 
"serol. bar auto. thumb", -' the GEL INO 
VERTICAL) ; | (*seroll bar auto: thumb) 
1. Ua Leis 
ELSE 
temp {27} := FALSE; 
ENDIF; 
temp {28} := (GET_INFO (the_window, "scroll bar", HORIZONTAL) <> 0); 
IF temp {28} 
THEN 
temp {29} := GET INFO (the window, "scroll bar _auto_ thumb", 
HORLZONLAL) ; 
ELSE 
temp {29} := FALSE; 
ENDIF’; 
ELSE 
temp {26} := FALSE; 
temp {27} := FALSE; 
temp {28} := FALSE; 
temp {29} := FALSE; 
ENDIF’; 
window_array {the count} := temp; 
UNMAP (the window) ; 
the count <= the count — 1; 
ENDLOOP ; 
eve$x_number of windows := 0; 
ENDPROCEDURE; 


Example of Mapping Saved Windows 


Example 7—7 shows the procedure sample_map_saved_windows, which 
maps windows whose descriptions have been saved previously. Sample_ 
map_saved_windows is passed the array window_array containing 
information about windows that have previously been saved and then 
unmapped. You can see an example of how such an array is created in 
Example 7-6. The procedure maps the windows to buffers, giving the 
windows the same characteristics they had before they were unmapped. 


The procedure includes the following built-ins: 


¢ SET (SCROLL_BAR) 
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SET (SCROLL_BAR_AUTO_THUMB) 
SET (WIDGET) 
SET (WIDGET_CALLBACK) 


Note: DIGITAL does not guarantee that this example will work 
successfully with future versions of EVE. 


Example 7-7 Procedure Mapping Saved Windows 


PROCEDURE sample map saved windows (window array) 


LOCAL 


ON ERROR 


temp, 


the length, 
length remaining, 


the top, 


the Count, 
scroll bar widget, 
screen length; 


[TPUS CONTROLC]: 
eveSmessage (EVES RESETUPWINDOWS) ; 
eveSsetup windows (window array) ; 


UPDATE 


ABORT ; 
[OTHERWISE]: 


endon_er 


screen l 


ror; 


ength 


(ALL) ; 
eveSlearn_ abort; 


eveSget_screen height; 


eve$Sunmap_all_ windows; 
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eve$x number of windows 
the count 


LOOP 


Ls 


window array {0}; 


EXITIF the count > GET INFO (window_array, "high_index"); 


temp 


window_array {the count}; 


eve$Smap window (temp {1}, temp {2}, temp {3}, temp {4}, temp {5}, 
temp {7}); 


IF temp {95} 


THEN 


temp {6}, 
ON 


SET (STATUS LINE, temp {1}, NONE, temp {8}); 


IF temp 
THEN 
SET 
ENDIF; 
IF temp 
THEN 
SET 
ENDIF; 
IF temp 
THEN 
SET 
ENDIF; 
IF temp 
THEN 
SET 
ENDIF; 


1-2.9'} 
(STATUS LINE, 
Ako y 
(STATUS LINE, 
ti} 
(STATUS LINE, 
Ved} 


(STATUS LINE, 


temp 


temp 


il}, 


{1}, 


temp {1}, 


temp 


{1}, 


BLINK, temp {8}); 


BOLD, temp {8}); 


REVERSE, temp {8}); 


UNDERLINE, temp {8}); 


(continued on next page) 
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(Cont.) Procedure Mapping Saved Windows 


ENDL 
IF G 
THEN 


ENDI 
LPG 
THEN 


IF temp {22} 

THEN ; 

SET (STATUS LINE, temp {1}, SPECIAL GRAPHICS, temp {8}); 
ENDIF; 

ENDIF; 

SET (WIDTH, temp {1}, temp {9}); 

SET (TEXT, temp {1}, temp {13}); 

IF temp {14} 


THEN 

SET (VIDEO, temp {1}, BLINK); 
ENDIF; 
IF temp {16} 
THEN 

SET (VIDEO, temp {1}, BOLD); 
ENDIF’; 
IF temp {18} 
THEN 

SET (VIDEO, temp {1}, REVERSE) ; 
ENDIF; 
IF temp {20} 
THEN 

SET (VIDEO, temp {1}, UNDERLINE) ; 
ENDIF; 
SET (PAD, temp {1}, temp {23}); 
Sole? (temp (ij, emp {24137 
the: count. <= the: count a1; 
OOP; 


ET INFO (temp {25}, "type") = STRING 


Sel .{KEY MAP’ List, temp. (25), temp.-(i-}) 7 
BE; 


ET INFO (SCREEN, "decwindows") 
IF temp {26} 
THEN 
scroll bar widget := SET (SCROLL BAR, ! This statement 
temp {1}, ! uses the 
VERTICAL, ON); ! SET (SCROLL BAR) 
L DULLeanis 

SET (WIDGET CALLBACK, ! This statement uses the 
scroll bar widget, ! SET (WIDGET CALLBACKS) 
"eveSscroll dispatch", Yuasa lt=-ins 
iz! ) : 

SET (WIDGET, ! This statement uses 
scroll bar widget, ! the SET (WIDGET) 
eve$$scroll bar callbacks); ) bULIC=ins 

eve$Sscroll bar_window (scroll bar widget) := temp {1}; 

IF temp {27} 

THEN 

SET (SCROLL BAR AUTO THUMB, ! This statement uses the 
temp {1}, VERTICAL, ON); ! SET (SCROLL BAR AUTO THUMB) 
} Dua Leas 
ENDIF; 


(continued on next page) 
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Example 7-7 (Cont.) Procedure Mapping Saved Windows 


ENDIF; 
IF temp {28} 
THEN 
scroll bar widget := SET (SCROLL BAR, temp {1}, HORIZONTAL, 
| ON) ; 
SET (WIDGET CALLBACK, scroll bar widget, "“eve$scroll_ dispatch", 
"h’); 
SET (WIDGET, scroll _ bar widget, eve$$scroll bar callbacks); 
eve$$scroll bar window (scroll bar_widget) := temp {1}; 
IF temp {29} 
THEN 
SET (SCROLL BAR AUTO THUMB, temp {1}, HORIZONTAL, ON); 
ENDIF; 
ENDIF; 
ENDIF; 
UPDATE (ALL); 
the count: <=-1; 
LOOP 
EXITIF the count > GET INFO (window_array, "high index"); 
temp := window_array {the count}; 
SET (SCROLLING, temp {1}, ON, temp {10}, temp {11}, temp {12}); 
the count := the count + 1; 
ENDLOOP ; 


SET (PROMPT AREA, screen length - 1, 1, REVERSE); 
ENDPROCEDURE; 


7./.8 | Handling Callbacks from a Scroll Bar Widget 


Example 7—8 shows one of the ways an application can use the statements 
POSITION (integer) and SET (WIDGET). The procedure is a portion of the 
EVE procedure eve$scroll_dispatch. You can find the original version in 
SYSSEXAMPLES:EVE$SDECWINDOWS.TPU. For more information about 
using the files in SYS$SEXAMPLES as examples, see Section 7.7. 


The procedure eve$scroll_dispatch is the callback routine handling 
callbacks from scroll bar widgets. The portion of the procedure shown 
here determines where to position the editing point based on how the user 
has changed the scroll bar slider. The procedure fetches the position of 
the slider with the built-in GET_INFO (widget_variable, "widget_info") 
and positions the editing point to the line in the buffer equivalent to 

the slider’s position in the scroll bar. Finally, the procedure updates the 
scroll bar’s resource values. For more information about the resource 
names used with the scroll bar widget, see the VMS DECwindows Toolkit 
Routines Reference Manual. 


EVE uses the following constants in this procedure: 


e¢ EVE$DWT$C_NINC - A constant for the string "inc". This is the 
resource name for the amount that the scroll bar slider position is to 
be incremented or decremented when a scroll bar button is pressed. 
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° EVE$DWT$C_NPAGE_INC - A constant for the string "pageInc". This 
is the resource name for the amount that the scroll bar slider position 
is to be incremented or decremented when a click occurs within the 
scroll bar above or below the slider. 


e EVE$DWT$C_NMAX VALUE - A constant for the string "maxValue". 
This is the resource name for the maximum value of the scroll bar 
slider position. 


¢ EVES$DWT$C_NMIN_VALUE - A constant for the string "minValue". 
This is the resource name for the minimum value of the scroll bar 
slider position. 


e EVE$DWT$C_NVALUE - A constant for the string "value". This is 
the resource name for the top of the scroll bar slider position. 


¢ EVESDWT$C_NSHOWN - A constant for the string "shown". This is 
the resource name for the size of the slider. 


e EVE$SDWT$C_CRVALUE_CHANGE_CALLBACK - A constant for the 
callback reason code DWT$C_CR_VALUE_CHANGED. This reason 
code indicates that the user changed the value of the scroll bar slider. 


e¢ EVE$K_CLOSURE - A constant for the string "closure", used as an 
index for the array returned by GET_INFO (WIDGET, "callback_ 
parameters", array). 


¢ EVE$K_REASON_CODE - A constant for the string "reason_code", 
used as an index for the array returned by GET_INFO (WIDGET, 
"callback_parameters", array). 


e¢ EVE$K_WIDGET - A constant for the string "widget", used as an 
index for the array returned by GET_INFO (WIDGET, "callback_ 
parameters", array). 


Example 7-8 EVE Procedure Handling Callbacks from a Scroll Bar Widget 


PROCEDURE eveS$scroll dispatch 
LOCAL status, 
widget called, 
widget tag, 
widget reason, 
scroll bar values, 
linenum, 
temp array, 


ON_ ERROR 
[TPUS CONTROLC] : 
eveSlearn_ abort; 
ABORT; 
ENDON_ERROR 


@ status := GET INFO (WIDGET, "callback parameters", temp_array); 


(continued on next page) 
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Example 7-8 (Cont.) EVE Procedure Handling Callbacks from a Scroll Bar Widget 


widget_called := temp_array {eveSk widget}; 
widget_tag := temp_array {eve$k closure}; 
widget reason := temp_array {eve$k_reason_code}; 


POSITION (eve$$scroll_ bar window {widget _called}); 


scroll bar_values := CREATE ARRAY; 
scroll bar values {eveSdwt$c_ninc} := 0; 
scroll _bar_values {eveSdwt$c_npage inc} := 0 
scroll bar values {eveSdwt$c_nmax_ value} 
scroll bar_values {eveS$dwtSc_nmin_value} := 
scroll bar values {eve$dwt$c nvalue} := 0; 
scroll _ bar values {eveSdwt$c_nshown} := 0; 


| 
oo. 


@ status := GET INFO (widget called, "widget info", scroll _ bar values); 


! The deleted statements scroll the window as dictated 
! by the callback reason. 


CASE widget_reason 


[eveSdwt$c_crvalue_change_callback]: 


IF (scroll _bar_values {eveS$dwt$c_nvalue} = 
scroll _ bar values {eve$dwt$c_nmin_value}) 

THEN 
POSITION (beginning of (current_buffer)); 

ELSE 
POSITION (scroll bar values {eve$dwt$c_nvalue}); 


ENDIF; 
scroll bar values {eve$dwt$c_ninc} := 1; 
scroll bar_values {eveSdwt$c_npage inc} := scroll bar _values {eve$dwt$c_nshown} 


© SET (WIDGET, widget called, scroll bar values); 


ENDPROCEDURE; 


GET_INFO (WIDGET, "callback_parameters", array) returns an array 
containing the values for the current callback. The array elements 
are indexed by the strings "widget", "closure", and "reason_code". 


(continued on next page) 
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Example 7-8 (Cont.) EVE Procedure Handling Callbacks from a Scroll Bar Widget 


referencing the widget that is calling back, the widget’s closure value, 
and the reason code for the callback. 


GET_INFO (widget, "widget_info", array) allows you to fetch 
information from a widget. The array parameter is indexed by 

the resource names associated with the specified widget. Note that 
resource names are case sensitive. Note, too, that the set of supported 
resources varies from one widget type to another. When you use GET_ 
INFO (widget, "widget_info", array), VAXTPU queries the widget for 
the requested information and puts the returned information in the 
array elements. Any previous values in the array are lost. 


POSITION (Gnteger) allows you to move the editing point to the record 
specified by the parameter integer. VAXTPU interprets this parameter 
as a record number. 


SET (WIDGET, widget, array) allows you to set resource values for 
the specified widget. The array parameter is indexed by the resource 
names associated with the specified widget. Note that resource names 
are case sensitive. Note, too, that the set of supported resources varies 
from one widget type to another. 


7.7.9 Example of Implementing the COPY SELECTION Operation 


Example 7—9 shows one of the ways an application can use the READ_ 
GLOBAL_SELECT built-in. The procedure is a modified version of the 
EVE procedure eve$stuff_global_selection. You can find the original 
version in SYS$EXAMPLES:EVE$MOUSE.TPU. For more information 
about using the files in SYSSEXAMPLES as examples, see Section 7.7. 


The procedure performs the following tasks: 


Saves the location of the editing point and the buffer’s current mode. 


Checks that the DECwindows version of EVE is enabled and that EVE 
does not have input focus. 


Obtains the location of the pointer cursor and positions the editing 
point at that location. 


Sets the text insertion mode to the insert setting. 


Reads the string-formatted contents of the primary global selection. 
(In this context, the parameter "STRING" means that the calling 
application is asking the application that owns the global selection for 
the string-formatted information in the specified global selection. ) 


Restores the editing point location and text insertion mode to their 
previous values. 
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EVE binds this procedure to the MB3 key to implement the DECwindows 
COPY SELECTION operation from another application to EVE. 


Example 7-9 EVE Procedure Implementing the COPY SELECTION Operation 


PROCEDURE eveSstuff global selection 


LOCAL saved position, 
saved mode, 
this buffer, 
the window, 
the column, 
the row; 


ON ERROR 
[TPUS_CONTROLC]: 
IF saved_mode = OVERSTRIKE 
THEN 
SET (saved_mode, this buffer); 
ENDIF; 
eveSSrestore position (saved position) ; 
eveSlearn_ abort; 


ABORT; 
[OTHERWISE] : 
IF saved_mode = OVERSTRIKE 
THEN 
SET (saved_mode, this buffer); 
ENDIF; 


eveS$Srestore position (saved position); 
ENDON_ERROR; 


this buffer := current_buffer; 
saved_position := MARK (FREE CURSOR) ; 
saved_mode := GET _ INFO (this buffer, "mode"); 
IF eve$x_decwindows active 
THEN 
IF not GET INFO (SCREEN, "input _focus") 
THEN 
IF LOCATE MOUSE (the window, ! This statement uses 
the column, the_row) ! the LOCATE MOUSE built-in. 
THEN 


IF the row <> 0 
IF the window <> eve$choice window 
THEN 
POSITION (MOUSE) ; 
SET (INSERT, this buffer) ; 


READ GLOBAL SELECT (PRIMARY, "STRING") ; ! This statement 

| ! using READ GLOBAL SELECT 
! reads the string- 

! formatted contents 

! of the primary 


global selection. 


(continued on next page) 
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Example 7-9 (Cont.) EVE Procedure Implementing the COPY SELECTION Operation 


eveS$restore position (saved position); 
SET (saved mode, this buffer); 
UPDATE (CURRENT WINDOW) ; 
RETURN (TRUE) ; 
ENDIF; 
ENDIF; 
ENDIF; 
ENDIF; 
ENDIF; 


RETURN (FALSE) ; 


ENDPROCEDURE; 


Example of Reactivating a Select Range 


Example 7-10 shows one of the ways an application can use the SET 
(GLOBAL_SELECT) built-in. The procedure is a modified version of the 
EVE procedure eve$restore_primary_selection. You can find the original 
version in SYS$EXAMPLES:EVE$MOUSE.TPU. For more information 
about using the files in SYS$EXAMPLES as examples, see Section 7.7. 


The procedure eve$restore_primary_selection reactivates EVE’s select range 
when EVE regains input focus. 


Example 7-10 EVE Procedure Reactivating a Select Range 


PROCEDURE eveSrestore primary selection 
LOCAL saved position; 


ON ERROR 
[TPUS CONTROLC] : 
eveSSrestore position (saved position); 
eveSlearn_ abort; 
ABORT; 
[OTHERWISE]: 
eveSSrestore position (saved position) ; 
ENDON ERROR; 


IF NOT eve$x_decwindows active 


THEN 
RETURN (FALSE) ; 
ENDIF; 
saved position := MARK (FREE CURSOR) ; 


{continued on next page) 
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Example 7-10 (Cont.) EVE Procedure Reactivating a Select Range 


IF GET INFO (eve$$x_ save select _array, "type") = ARRAY 
THEN 
CASE eveS$x_save_ select array {"type"} 
[RANGE] : 


eveSselect a range (eveS$x_save_select_array {"start"}, 
eve$SSx_save_select_array {"end"}); 
eveS$x_state_ array {eveS$k_select_all_ active} := 
eveS$x_save_select_array 
{"selece all"); 
POSITION (eveS$x_save_select_array {"current"}); 
evesstart_pending delete; 


[MARKER] : 
POSITION (eve$$x save_select_array {"start"}); 
eveSx select position := select (eve$x_highlighting) ; 


POSITION (eve$$x_save_select_array {"end"}); 
eveSstart pending delete; 
[OTHERWISE] : 
RETURN (FALSE) ; 
ENDCASE; 


eveS$restore position (saved position) ; 
eveS$found_post_filter; ! This is necessary if the 
L -Gursor- 2s ‘outside: the vselecction-: 


eveS$x_save_select array {"type"} := 0; 
UPDATE (current window) ; 

IF eve$Sx decwindows active 

THEN 


SET (GLOBAL SELECT, SCREEN, PRIMARY) ; ! This statement using 

! SET (GLOBAL SELECT) 

! requests ownership of 

! the primary global selection. 
ENDIF’; 

RETURN (TRUE) ; 


ENDIF; 
RETURN (FALSE) ; 
ENDPROCEDURE,; 


Example of Implementing the DECwindows COPY SELECTION 


Operation from EVE to Another Application 
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Example 7-11 shows one of the ways a layered application can use the 
WRITE_GLOBAL_SELECT built-in. The procedure is a modified version 
of the EVE procedure eve$write_global_select. You can find the original 
version in SYS$EXAMPLES:EVE$MOUSE.TPU. For more information 
about using the files in SYS$SEXAMPLES as examples, see Section 7.7. 


The procedure implements the DECwindows COPY SELECTION operation 
from EVE to another application. The procedure determines what property 
of the primary global selection is being requested, obtains the value of the 
appropriate property using a GET_INFO statement or an EVE routine, 
and sends the information to the requesting application. 
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Example 7-11 EVE Procedure implementing COPY SELECTION 


EVE uses this routine 
to respond to requests 
for information about 
selections. 


PROCEDURE eveSwrite global select 


LOCAL saved position, 

che data, 

temp array, 
Lotal Janes, 
the: Line, 
status, 

eob flag, 
percent; 


ON_ERROR 
[OTHERWISE] : 
eveSSrestore position (saved position); 
ENDON_ ERROR; 


saved_position := MARK (FREE CURSOR) ; 


IF NOT eve$x decwindows active 


THEN 
RETURN (FALSE) ; 
ENDIF; 
Une “deta. “3S '-hy 
temp _array := GET INFO (SCREEN, "event", GLOBAL SELECT) ; 
! Finds out which global selection and which property 
! of the global selection are the subject of the 
! information request. 
CASE temp array {2} ! Determines the property requested by other application. 


["STRING", "“TEXT"]: ! If one of these strings is requested, the 
! procedure sends the text in the global 
! selection to the requesting application. 


CASE temp array {1} ! Checks which global selection was specified. 
[PRIMARY]: 


IF eve$x select position <> 0 
THEN 
POSITION (GET_INFO (eve$Sx select position, “buffer")); 


(continued on next page) 
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Example 7-11 (Cont.) EVE Procedure Implementing COPY SELECTION 


IF GET INFO (eve$x_select_position, "type") = RANGE 
THEN 
the data := STR (eve$x select position); 
KLSE 
IF GET_INFO (eve$x_select_position, "type") = MARKER 
THEN 
the data := STR (eve$select_a_range (eve$x_select_position, 
MARK (FREE CURSOR) )); 
KLSE 
the_data := NONE; 
ENDIF; 
ENDIF; 
eveSSrestore position (saved_position) ; 
ENDIF; 
[OTHERWISE] : 
the data := NONE; 
ENDCASE; 
[OTHERWISE] : 
the data := NONE; ! The procedure does not send data if 
! the requesting application has asked 
! for something other than the text, 
! the file name, or the line number. 
ENDCASE; 


WRITE GLOBAL SELECT (the data); 


ENDPROCEDURE; 


! This statement sends the 
' requested information to 
! the requesting application. 
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CDA Converter Architecture 


CDA Converter 


The CDA Converter Architecture defines a methodology to simplify the 
conversion of compound documents. Compound documents contain 
integrated components such as proportionally spaced text, synthetic 
graphics, and scanned or natural images. For more information on 
compound documents or the Compound Document Architecture, see the 
VMS Compound Document Architecture Manual. 


The CDA Converter Architecture is implemented through the following 
applications: 


e The CDA Converter 
e The Character Cell Viewer 
e The supported front and back ends 


The following sections discuss each of these applications in more 
detail. Note that a DDIF Viewer and a PostScript are supported on 
VMS DECwindows systems. These viewers are described in the VMS 
DECwindows User’s Guide. 


The CDA Converter is an integral part of the Compound Document 
Architecture. It enables you to translate your compound document files to 
and from various file-encoding formats. The CDA Converter can be viewed 
as a “black box” that reads in an input file of the specified file-encoding 
format and converts it to an output file of the specified file-encoding 
format. 


To accomplish this conversion, the CDA Converter uses an in-memory 
format as the integral step in the conversion process. The converter 
reads the input file and translates it to a CDA in-memory format, and 
then translates this in-memory format to the specified output format. 

In other words, any input file-encoding format that is supported by the 
CDA Converter can be translated to a CDA in-memory format, and this 
in-memory format can subsequently be converted to any supported output 
file-encoding format. Figure 8—1 illustrates these basic stages of document 
conversion. 
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8.1 CDA Converter 


Figure 8-1 Stages of Document Conversion 
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8.1.1 Components of a Converter 


From the user’s perspective, the converter is a “black box” that reads in 
the specified input file and converts it to the specified output file. For 
this single converter to be able to convert the wide variety of supported 
file-encoding formats, it actually comprises the following four parts: 
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An interface (both a command line interface and an interface that is 
callable from within an application program) 


The CDA Converter Kernel that performs all the functions that must 
be completed for each conversion process, regardless of input and 
output formats 


A front end that converts a particular input format to the in-memory 
format 


A back end that converts the in-memory format to a particular output 
format 


The relationship of the various converter components is shown in 
Figure 8—2. 


When you invoke the converter, you always invoke the converter kernel 
first. This kernel performs the following functions: 


It performs all of the “generic” conversion functions that must be 
completed for every document conversion, regardless of input and 
output formats. 


It invokes the appropriate front end to translate the input file to the 
CDA in-memory format. 


It invokes the appropriate back end to translate the CDA in-memory 
format to an output file of the specified format. 


CDA Converter Architecture 
8.1 CDA Converter 


Figure 8-2 Converter Components Diagram 
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The CDA Converter, therefore, actually consists of the CDA Converter 
Kernel, one front end for each supported input file-encoding format, and 
one back end for each supported output file-encoding format. The kernel 
translates the various file formats by calling the appropriate front end and 
back end to perform the requested conversion. 


For example, if you have the CDA Converter Kernel, a DDIF front end, 
and an Analysis back end, you can invoke the converter to translate a 
DDIF-encoded input file to an Analysis-encoded output file. The common 
converter kernel invokes the DDIF front end and the Analysis back end 
to perform the requested conversion. In general, front ends and back ends 
are “paired.” That is, if a file-encoding format is supported by a front 
end, it generally is also supported by a back end. However, this is not 
always the case. For example, the Analysis back end does not have a 
corresponding front end. 


The front ends and back ends that are provided with the operating system 
are documented later in this chapter. The interfaces to the CDA Converter 
are as follows: 


¢ A DCL command line interface (CONVERT/DOCUMENT). 


e¢ <A callable interface (the CONVERT routine) that is accessible from 
application programs (see the VMS Compound Document Architecture 
Manual for more information). 


Each of these interfaces is discussed in the following sections. The 
Character Cell Viewer is discussed in Section 8.2. The supported input 
formats are discussed in Section 8.3 and the supported output formats are 
discussed in Section 8.4. 
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8.1.2 DCL Command CONVERT/DOCUMENT 


8.2 


The DCL command CONVERT/DOCUMENT invokes the conversion of 
a revisable format file to another revisable or final form file from the 
DCL command line. Please note that this command can only be used if 
you have DECwindows installed on your system. This command has the 
following format: 


CONVERT/DOCUMENTT[/OPTIONS=filespec] 
input-file//FORMAT=fmt-name] output-file[//FORMAT=fmt-name] 


The /FORMAT qualifier enables you to specify the encoding formats of the 
input and output files. (DDIF is the default input and output format.) The 
format keywords for the supported input and output formats are listed in 
Table 8-1. 


Table 8-1 Converter Format Keywords 


Input Formats Output Formats 
DDIF DDIF 

TEXT TEXT 

N/A PS 

N/A ANALYSIS 


The /OPTIONS qualifier enables you to specify a file that contains options 
to be applied during the conversion of the file. Each line of the file specifies 
a format name that can contain uppercase and lowercase alphabetic 
characters, digits, dollar signs, and underscores, optionally preceded by 
spaces and tabs, and terminated by any character other than those listed. 
Alphabetic case is not significant. The syntax and interpretation of the 
text that follows the format name are specified by the supplier of the front 
and back ends for the specified format. Multiple lines that specify the 
same format are permitted. 


Character Cell Viewer 


The Character Cell Viewer is an application that enables you to view 
compound document files on a character cell terminal or workstation 
window. This character cell viewer works with the CDA Converter 
Architecture, so that a file of any input format supported by CDA can 
be viewed on a character cell terminal. 


The Character Cell Viewer works by converting an input file to the in- 
memory format used by the CDA Converter. This in-memory format is 
then formatted for output to the screen. In other words, the Character 
Cell Viewer is a specific instance of the CDA Converter in which the 
output format is a screen display. 


The interfaces to the Character Cell Viewer are as follows: 


e A DCL command line interface (VIEW) 


OS 
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e A callable interface (the CONVERT routine) that is accessible from 
application programs 


Each of these interfaces is discussed in the following sections. The 
supported input formats are discussed in Section 8.3. 


8.2.1 DCL Command VIEW 


The DCL command VIEW invokes the Character Cell Viewer, which 
lets you view a compound document file on a character cell terminal or 
DECwindows display. Note that many of the text display attributes are 
not processed when displaying the document, because of the limitations 
of the viewing device. For example, the blink, underlining, and bold 
attributes are not processed. 


The VIEW command has the following format: 
VIEW input-file[/qualifiers] 


The input file specifies the name of the file to be viewed. You cannot use 
wildcard characters in the file specification. The default input file-encoding 
format is DDIF, and the default file type is DDIF. Valid input file formats 
are DDIF and TEXT; these input formats are described in more detail in 
Section 8.3. 

The qualifiers that you can specify to the view command are as follows: 

e /FORMAT{=format-name] 


Specifies the format of the input file. The default format is DDIF. 
The appropriate front end must be available in SYS$LIBRARY for the 
specified format-name. The valid formats are DDIF and TEXT. 


¢ /OUTPUT|=output-file-spec] 


Specifies a file that receives the text output. The default is 
/NOOUTPUT. If an output file specification is not specified, the output 
file specification defaults to input-file.LIS. If this qualifier is specified, 
the output of the VIEW command is not displayed on the screen, but 
is instead written to the specified file. Note that if you specify the 
/OUTPUT qualifier, you cannot also specify the /PAGE qualifier. 


e /PAGE 


Controls the display of output, providing the same effect as the DCL 
command TYPE/PAGE when used on a non-DECwindows device. The 
default is /NOPAGE. The /PAGE qualifier has no effect when used 
with a DECwindows display because the scroll bars provide the same 
capability. Note that if you specify the /PAGE qualifier, you cannot 
also specify the /OUTPUT qualifier. 


e¢ /OPTIONS=file-spec 


Specifies a file that contains options to be applied during the 
conversion of the file to the CDA in-memory format. The default 
file type is DDIF$OPTIONS. 


e /SELECT=select-list 
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Allows the user to tailor the CDA Viewer output. The selection items 
you can specify are as follows: 


[NO]GRAPHICS Directs the viewer either to mark the location 
of graphics embedded in the DDIF file being 
processed by the character cell viewer, or to 
ignore the graphics. 


[NO]JIMAGES Directs the viewer either to mark the location 
of the images embedded in the DDIF file being 
processed by the character cell viewer, or to 
ignore the images. 


[NO]TEXT Directs the viewer either to process the text 
contained in the DDIF file being processed, or to 
ignore the text. 


ALL Directs the viewer to process all information 
contained in the DDIF file being processed. 
[NO|SOFT_DIRECTIVES Directs the viewer either to process or ignore 


soft directives in the DDIF file being processed 
in order to format output. Soft directives specify 
such formatting commands as new line, new 
page, and tab. 


[NOJAUTO_WRAP Directs the viewer to perform word wrapping 
of any text that would exceed the right margin. 
NOAUTO_WRAP allows the text to exceed the 
margin. 

[NO]X_DISPLAY Directs the viewer to create a DECwindows 
widget to be used when viewing the file on a 
workstation display defined by the logical name 
DECWS$DISPLAY. NOX_DISPLAY, the default, 
invokes the character cell viewer. Note that X_ 
DISPLAY cannot be specified if the /OUTPUT 
qualifier is also specified. 


The default format is 


/SELECT = (GRAPHICS, IMAGES, TEXT, SOFT_DIRECTIVES, 
AUTO_WRAP, NOX_DISPLAY) 


Because the Character Cell Viewer is really a specific instance of the CDA 
Converter (where the output format is screen output), the CONVERT 
routine is used to invoke the Character Cell Viewer as well as the CDA 
Converter. For more information on the CONVERT routine, see the VMS 
Compound Document Architecture Manual. 


Input Formats 
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The CDA Converter Architecture works by supplying a common converter 
kernel and front and back ends to support the various input and output 
formats. The following sections describe each supported front end, the 
data mapping between that input format and the in-memory format, 

any data loss that might occur during the conversion, and any other 
information specific to that front end. 


8.3.1 


8.3.2 


8.4 


DDIF Front End 


Text Front End 


Output Formats 
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The DDIF front end reads a file encoded in DDIF format and converts the 
information in the file to the CDA in-memory structure. The following 
information is specific to the DDIF front end: 


Data Mapping. Because the input file format is DDIF, the information 
in the file maps directly to the CDA in-memory structure. 


Data Loss. The DDIF front end does not lose any data when 
converting a DDIF input file to the CDA in-memory structure. Again, 
this is because the input document type and the in-memory structure 
type are both DDIF. 


External File References. When the DDIF front end encounters an 
external file reference that is specified in the document header of your 
DDIF input file, it passes the reference through to the CDA Converter 
Kernel. 


Document Syntax Errors. If a document syntax error is encountered 
in the DDIF front end, that represents a fatal input processing error. 
The only way that this can occur is if the input document is invalid. 
If the DDIF front end does encounter a document syntax error, the 
conversion process is stopped and no further input processing is 
performed. 


The Text front end reads a standard text (DEC multinational) file and 
converts the information in the file to the CDA in-memory structure. The 
following information is specific to the Text front end: 


Data Mapping. When you invoke the converter for a Text input file, 
all of the text in the input file is mapped to DDIF text content. Line 
breaks and form feeds are mapped to DDIF directives. 


Data Loss. The Text front end does not lose any data when converting 
a Text input file to the CDA in-memory structure. This is because no 
structure information is contained in a text file. 


External File References. Text files do not contain external file 
references. Therefore, the Text front end does not evaluate external 
file references. 


Document Syntax Errors. Because text files do not have any syntax 
defined, syntax errors cannot be encountered by the Text front end. 


The following sections describe each back end supported by the CDA 
Converter Architecture, the data mapping between the in-memory format 
and the particular output format, any data loss that might occur during 


the conversion, and any other information specific to that back end. 
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8.4.1 DDIF Back End 


The DDIF back end takes the CDA in-memory structure that has been 
converted from some input format, converts it to a DDIF output format, 
and writes the information to the specified DDIF output file. The following 
information is specific to the DDIF back end: 


¢ Data Mapping. When you invoke the converter with the DDIF back 
end, the data mapping between the information in the CDA in-memory 
structure and the converted output file is one-to-one. This is because 


the in-memory structure type and the output document type are both 
DDIF-. 


¢ Data Loss. The DDIF back end does not lose any data when converting 
a CDA in-memory structure to a DDIF output file. Again, this is 
because the in-memory structure type and the output document type 
are both DDIF. 


8.4.2 Text Back End 


The Text back end takes the CDA in-memory structure that has been 
converted from some input format, converts only the text content of the 
file, and writes the information to the specified text output file. The 
following information is specific to the Text Back End: 


e Data Mapping. When you invoke the converter for a text output file, 
all Latin1 text is written to the output text file. 


e Data Loss. When the Text back end is converting the in-memory 
structure to a text output file, all graphics, images, attributes, and 
formatting information are lost. 


e Processing Options. The text back end supports the following options: 


ASCII_FALLBACK This option causes the back end to output text 
in 7-bit ASCII. The fallback representation of 
the characters is described in the ASCII ANSI 
standard. 

CONTENT_MESSAGES This option causes the back end to put a 
message in the output file each time a nontext 
element is encountered in the in-memory CDA 
structures. 


8.4.3. PostScript Back End 


The PostScript back end takes the CDA in-memory structure that has 
been converted from some input format, converts the content of the file, 
and writes the information to the specified text output file. The following 
information is specific to the PostScript Back End: 


e Data Mapping. When you invoke the converter for a PostScript output 
file, all document content is written to the output file. ( 


e Data Loss. When converting the in-memory structure to a PostScript 
output file, all document content is converted. 
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Processing Options. 


The PostScript back end supports various processing options. The 
keyword is separated from its assigned value by one or more spaces or 
tabs. Note that, for all of the measurement options, the default unit 
of measure is inches. Other supported units of measure are points, 
centimeters (cm), and millimeters (mm). 


The processing options are described as follows: 
— Paper Size Processing Option. 


The PAPER_SIZE paper-size option lets you specify the size of the 
paper to be used when formatting the resulting PostScript output 
file. Valid values for paper-size are as follows: 


Keyword Size 

AO 841 x 1189 millimeters 
A1 594 x 841 millimeters 
A2 420 x 594 millimeters 
A3 297 x 420 millimeters 
A4 210 x 297 millimeters 


A 8.5 x 11 inches 
B 11 x 17 inches 
C 17 x 22 inches 
D 22 x 34 inches 
E 34 x 44 inches 


LEDGER 11 x 17 inches 
LEGAL 8.5 x 14 inches 
LETTER 8.5 x 11 inches 
LP 13.7 x 11 inches 
VT 8 x 5 inches 


The A paper size (8.5 x 11 inches) is the default. 
— Paper Height Processing Option. 


The PAPER_HEIGHT paper-height processing option, in 
combination with the PAPER _WIDTH processing option, lets 
you specify a paper size other than one of the predefined values 
provided. The default paper height is 11 inches. 


— Paper Width Processing Option. 


The PAPER_WIDTH paper-width processing option, in combination 
with the PAPER HEIGHT processing option, lets you specify a 
paper size other than one of the predefined sizes provided. The 
default paper width is 8.5 inches. 
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Top Margin Processing Option. 


The PAPER_TOP_MARGIN top-margin processing option lets you 
select the width of the margin provided at the top of the page. The 
default value is 


Bottom Margin Processing Option 


The PAPER_BOTTOM_MARGIN bottom-margin processing option 
lets you select the width of the margin provided at the bottom of 
the page. The default value is .25 inches. 


Left Margin Processing Option 


The PAPER_LEFT_MARGIN left-margin processing option lets you 
select the width of the margin provided on the left-hand side of the 
page. The default value is .25 inches. 


Right Margin Processing Option. 


The PAPER_RIGHT_MARGIN right-margin processing option lets 
you select the width of the margin provided on the right-hand side 
of the page. The default value is .25 inches. 


Paper Orientation Processing Option. 


The PAPER_ORIENTATION orientation processing option lets you 
select the paper orientation to be used in the output PostScript file. — 
The valid values for the orientation argument are as follows: 


Keyword Meaning 

PORTRAIT The page is oriented so that the larger dimension 
is parallel to the vertical axis. 

LANDSCAPE The page is oriented so that the larger dimension 


is parallel to the horizontal axis. 
The default is PORTRAIT. 
Eight Bit Output Processing Option. 


The EIGHT_BIT_OUTPUT eight-bit-output-state processing option 
lets you select whether or not the PostScript back end should use 
8-bit output. You can specify a value of either ON or OFF for the 
eight-bit-output-state argument. The default is ON. 


Output Buffer Size Processing Option. 


The OUTPUT_BUFFER_SIZE output-buffer-size processing option 
lets you select the size of the output buffer. The value you specify 
must be within the following range: 


64 < output — buf fer — size < 256 


The default is 132. 
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— Soft Directives Processing Option. 


The SOFT_DIRECTIVES soft-directives-state processing option 
lets you select whether or not the PostScript back end processes 
soft directives in the DDIF file in order to format output. (Soft 
directives specify such formatting commands as new line, new 
page, and tab.) You can specify a value of either ON or OFF for 
the soft-directive-state argument. The default is ON. 


— Word Wrap Processing Option. 


The WORD_WRAP word-wrap-state processing option lets you 
specify whether or not the PostScript back end performs word 
wrapping of any text that would exceed the right margin. You 
can specify a value of either ON or OFF for the word-wrap-state 
argument. The default is ON. If you specify OFF, the PostScript 
back end allows text to exceed the right margin. 


— Page Wrap Processing Option. 


The PAGE_WRAP page-wrap-state processing option lets you 
specify whether or not the PostScript back end performs page 
wrapping of any text that would exceed the bottom margin. You 
can specify a value of either ON or OFF for the page-wrap-state 
argument. The default is ON. 


— Layout Processing Option. 


The LAYOUT layout-state processing option lets you specify 
whether or not the PostScript back end processes the layout 
specified in the DDIF document. You can specify a value of either 
ON or OFF for the layout-state argument. The default is ON. 


8.4.4 Analysis Back End 


This back end produces an analysis of the CDA in-memory structure in 
the form of text output showing the named objects and values stored in 
the document. This is useful for debugging DDIF application programs. 


The Analysis back end supports an /INHERITANCE processing option that 
specifies that the analysis is shown with attribute inheritance enabled. 
Inherited attributes are marked by “[default]” in the output. 
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The term compound documents refers to files that may contain a 
number of integrated components including text, graphics, and scanned 
images. This chapter specifically describes VMS support for using the text 
from DECwindows compound documents that are structured in accordance 
with the Digital Data Interchange Format (DDIF) specification. Refer to 
the VMS Compound Document Architecture Manual for more information 
about compound documents. 


VMS commands and utilities, as well as existing application programs that 
accept text input, can now use the text content of DECwindows compound 
documents. 


To support the use of DDIF text, VMS RMS has implemented a new RMS 
file attribute, stored semantics, and a DDIF-to-text RMS extension. 
The value of the stored semantics attribute is called the file tag and 

it specifies how file data is to be interpreted. When file data is to be 
interpreted in accordance with the DDIF specification, the appropriate file 
tag is DDIF. The use of file tags is limited to disk files on VMS Version 5.1 
and later systems. 


The DDIF-to-text RMS extension transparently extracts text from DDIF 
files as variable-length text records that can be accessed through the VMS 
RMS interface. 


The enhancements made to support the reading of text from DDIF files are 
transparent to the user and to the application programmer. This support 
requires that all DDIF files in a VMS Version 5.1 environment be tagged 
with the DDIF file tag. DDIF files created by VMS and VMS layered 
products are tagged appropriately. 


Section 9.1 describes various VMS_file management commands and 
utilities that display, create, and preserve file tags where appropriate. 
Section 9.1 also describes the way various VMS commands and utilities 
respond to DDIF file input. Section 9.2 describes VMS support for DDIF 
files in heterogeneous computing environments. Section 9.3 describes the 
changes made to the VMS RMS program interface to support the stored 
semantics attribute and to control access to the content of DDIF files. 


9.1 VMS Commands and Utilities 


This section describes the VMS commands and utilities that support tag 
maintenance by displaying, creating, and preserving the RMS file tags 
used with DDIF files. It also provides additional information that is 
relevant to the way selected VMS commands and utilities respond to DDIF 
file input. 


9-1 


Support for Compound Documents 
9.1 VMS Commands and Utilities 


The following table lists the VMS commands and utilities that support tag 
maintenance. 


Command/Utility Tag Maintenance Function 
DIRECTORY/FULL Displays file tag 
ANALYZE/RMS_FILE Displays file tag 

SET FILE/SEMANTICS Creates file tag 

VMS MAIL Preserves file tagt 

COPY Preserves file tagT 
BACKUP Preserves file tag 


tSee text for exceptions. 


Tags are made up of binary values that can be up to 64 bytes long and can 
be expressed using hexadecimal notation. The hexadecimal value of the 
DDIF tag, for example, is 2B0C8773010301. VMS permits you to assign 
mnemonics to tag values so that DCL commands like DIRECTORY/FULL 
and VMS utilities like FDL and ANALYZE/RMS_FILE display a mnemonic 
for the DDIF tag instead of the hexadecimal value. The following DCL 
commands have been included in the system startup command file to 
assign the mnemonic DDIF to the hexadecimal value for a DDIF tag: 


S DEFINE/TABLE=RMSSSEMANTIC TAGS DDIF 2B0C8773010301 
S DEFINE/TABLE=RMSSSEMANTIC OBJECTS 2B0C8773010301 DDIF 


Using the appropriate DEFINE commands, you can assign mnemonics for 
other tags, including tags used with international program applications. 


9.1.1 Displaying RMS File Tags 


9.1.1.1 


The DIRECTORY/FULL command and the Analyze/RMS_File Utility now 
display the RMS file tag for DDIF files. 


DIRECTORY/FULL 

Where applicable, the DIRECTORY/FULL command now provides the 
value of the stored semantics tag as part of the file information returned 
to the user. This is the recommended method for quickly determining 
whether or not a file is tagged. The following display illustrates how the 
DIRECTORY/FULL command returns the RMS attributes for a DDIF file 
named X.DDIF: 


xe DDE; 1 File ID: (767,20658,0) 


RMS attributes: Stored semantics: DDIF 
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9.1.1.2 ANALYZE/RMS FILE 
When you use the ANALYZE/RMS_FILE command to analyze a DDIF file, 
the utility returns the file tag as an RMS file attribute. 


FILE HEADER 
File Spec: USERDS: [TEST]X.DDIF;1 


Stored semantics: DDIF 


One ANALYZE/RMS_FILE command option is to create an output FDL 
file that reflects the results of the analysis. 


$ ANALYZE/RMS FILE/FDL filespec 


When you use this option for analyzing a tagged file, the output FDL 
file includes the file tag as a secondary attribute to the FILE primary 
attribute. This is illlustrated in the following FDL file excerpt: 


IDENT "9-JUN-1988 13:27:30 VAX/VMS ANALYZE/RMS FILE Utility" 


SYSTEM 


SOURCE VMS 
FILE 
ALLOCATION 3 
STORED SEMANTICS 6X’ 2B0C8773010301’ ! DDIF 


9.1.2 Creating RMS File Tags 


The CDA$CREATE_FILE routine in the Compound Document 
Architecture toolkit creates and tags DDIF files. However, you may 
encounter a DDIF file that was created without a file tag or a DDIF file 
whose file tag was not preserved during file processing. 


The DCL command SET FILE provides a new qualifier, 
/LNOJSEMANTICS, that permits you to tag a DDIF file through the 

DCL interface for VMS Version 5.1 systems. You can also use the qualifier 
to change a tag or to remove a tag from a file. 


The following command line tags the file X.DDIF as a DDIF file by 
assigning the appropriate value to the /SEMANTICS qualifier: 


S$ SET FILE X.DDIF/SEMANTICS=DDIF 


See Section 9.1 for information about how to use logical name tables to 
assign a mnemonic to a tag. 
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A subsequent DIRECTORY/FULL command displays the following line as 
part of the file header: 


RMS attributes: Stored semantics: DDIF 


The next example illustrates how to use the SET FILE command to delete 
an RMS file tag: 


S$ SET FILE X.DDIF/NOSEMANTICS 


9.1.3. Preserving RMS File Tags and DDIF Semantics 


The COPY command and the VMS Mail Utility preserve RMS file tags and 
DDIF semantics when you copy or mail a DDIF file on a VMS Version 5.1 
system, except for conditions described in Sections 9.2.2, 9.2.3, and 9.2.4. 


The Backup Utility always preserves file tags and semantics when you 
back up a DDIF file to magnetic tape. 


9.1.3.1 COPY Command 
This section describes the results of using the COPY command with DDIF 
files for various operations. 


When you copy a DDIF file to a disk on a VMS Version 5.1 system using 
the COPY command, VMS RMS preserves the DDIF tag and the DDIF 
semantics of the input file in the output file. 


When you copy a DDIF file to a nondisk device on a VMS Version 5.1 
system using the COPY command, VMS RMS does not preserve the 
DDIF tag or the DDIF semantics of the input file in the output file. 
Instead, VMS RMS writes the text from the input file to the output file as 
variable-length records. 


When you copy two or more DDIF and text files in any combination to a 
single output file, the output file takes the characteristics of the first input 
file, as shown in the following examples: 


1 In the first example, the first input file is a text file, so the output file 
(FOO.TXT) contains variable-length text records from X.TXT, Y.DDIF, 
and Z.TXT, but does not include the DDIF tag from Y.DDIF. 


S COPY XTX Y.DDIP AaVTXT FOO, TXT 


2 In the next example, the first input file (A.DDIF) is a DDIF file, so 
the output file (FOO.DDIF) includes the DDIF tag as well as the DDIF 
semantics from A.DDIF. The attempt to copy the text input file (Z.TXT) 
fails because there is no text-to-DDIF RMS extension, but the contents 
of B.DDIF and C.DDIF are copied to the output file. However, the 
output file has no practical use because, as a result of the way DDIF ( 
files are structured, only the data from the first input file (A.DDIF) is 
accessible in the output file. 


$ COPY A.DDIF,B.DDIF,2Z.TXT,C.DDIF FOO.DDIF 
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3 In the final example, the first input file (A.DDIF) is a DDIF file, so the 
output file (FOO.DDIF) includes the DDIF tag as well as the contents 
of A.DDIF. FOO.DDIF also includes the contents of B.DDIF and 
C.DDIF. Again, however, the output file has no practical use because, 
as a result of the way DDIF files are structured, only the data from 
the first input file (A.DDIF) is accessible in the output file. 


5 COPY ADDIE; BZDDIE,; CLDDIP “FOO. DDaF 


9.1.3.2 VMS Mail Utility 
The VMS Mail Utility preserves the DDIF file tag when DDIF files are 
mailed between Version 5.1 systems. The VMS Mail Utility also preserves 
the DDIF file tag when you create an output file on a VMS Version 5.1 
system using the EXTRACT command. 


When you read a mail message that is a DDIF file, the VMS Mail Utility 
outputs only the text portion of the file. Similarly, if you edit a DDIF mail 
file, you can access only the file text; the output file is a text file that can 
no longer be used as a DDIF file. However, if you forward a message that 
consists of a DDIF file, the VMS Mail Utility sends the entire DDIF file, 
including DDIF semantics and the DDIF tag, to the addressee. 


9.1.4 APPEND Command 


This section describes what happens when you attempt to use the 
APPEND command in conjunction with DDIF and text files. 


In the first example, the APPEND command appends a DDIF file to a text 
file: 


S APPEND X.DDIF Y.TXT 


The output file, Y.TXT, contains its original text records as well as text 
from the input file, X.DDIF, reformatted as variable-length text records. 


In the next example, the APPEND command appends a DDIF file to 
another DDIF file: 


S APPEND X.DDIF Y.DDIF 


The output file, Y.DDIF, contains the DDIF tag, the original contents 

of Y.DDIF, and the contents of X.DDIF. However, the portion of the file 
that contains X.DDIF is not accessible because of the way DDIF files are 
structured. 


In the final example, the APPEND command attempts to append a text 
file to a DDIF file: 


S APPEND X.TXT Y.DDIF 


This append operation fails because there is no text-to-DDIF RMS 
extension. 
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9.2 DDIF Support in a Heterogeneous Environment 


This section describes the implementation of DDIF support in two 
heterogeneous environments. The first heterogeneous environment 
includes VMS Version 5.1 systems and non-VMS systems. The second 
heterogeneous environment includes VMS Version 5.1 or earlier systems. 


9.2.1 EXCHANGE/NETWORK Command 


A new DCL command, EXCHANGE/NETWORK, has been created 

to support the transfer of files between VMS systems and non-VMS 
systems that do not support VMS file types. The EXCHANGE/NETWORK 
command transfers files in either record mode or block mode but can only 
be used when both systems support DECnet file transfers. 


To interactively tag a DDIF file and transfer the file between a non-VMS 
operating system and a VMS Version 5.1 system, do the following: 


1 Create the following file, assigning it the name DDIF.FDL: 


FILE 
ORGANIZATION sequential 
STORED SEMANTICS DDIF 
RECORD 
CARRIAGE CONTROL none 
FORMAT fixed 
SIZE 512 


2 Use the following DCL command to transfer the desired file: 


§ EXCHANGE/NETWORK/FDL=DDIF.FDL input filespec output _filespec 


See Chapter 10 for more information about the EXCHANGE/NETWORK 
command. 


9.2.2 Using the COPY Command in a Heterogeneous Environment 
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If you use the COPY command to copy tagged DDIF files to systems other 
than VMS Version 5.1 systems from a VMS Version 5.1 system, the results 
will vary depending on the target system: 


e Ifthe target system is a non-VMS system, the file is copied, but the 
DDIF tag is not preserved. 


e Ifthe target system is a VMS Version 5.1 or earlier system, the copy 
operation fails with the VMS RMS error message RMS$_SUPPORT, 
network operation not supported, and a secondary error message of 
RMS$_SEMANTICS, inconsistent usage of RMS Semantics. Error 
messages similiar to the following will appear: 


sCOPY-E-OPENOUT, error opening PWEDGE::[]TRY.DDIF;1 as output 
-RMS-F-SUPPORT, network operation not supported 
-RMS-E-SEMANTICS, inconsistent usage of RMS Semantics 
sCOPY-W-NOTCOPIED, ABCD4: [DAVIDS]TRY.DDIF;1 not copied 


9.2.3 


9.2.4 
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e Ifthe target system is a cluster alias for a mixed version cluster 
containing Version 5.1 or earlier systems, the result of the copy 
operation depends on whether the cluster node which actually handles 
the request is a Version 5.1 or earlier system. 


e If you use the COPY command to copy tagged DDIF files from Version 
5.1 systems to earlier systems while on an earlier system, the copy 
operation will fail with error message RMS$_NET, network operation 
failed at remote node and with a DAP status code of 16F, inconsistent 
usage of RMS Semantics. Error messages similiar to the following will 
appear: 


SCOPY-E-OPENIN, error opening ARC"davids password": :ABCD4: [DAVIDS]TRY.DDIF;1 as input 
-RMS-F-NET, network operation failed at remote node; DAP code = O1F7516F 
SCOPY-W-NOTCOPIED, ARC"davids password": :ABCD4: [DAVIDS]TRY.DDIF;1 not copied 


VMS Mail Utility in a Heterogeneous Environment 


If you try to send mail messages containing DDIF files to non-VMS 
systems that do not support tagged files, the VMS Mail Utility returns the 
NOACCEPTMSG error message, indicating that the remote node cannot 
accept the message format. 


Similarly, the VMS Mail Utility does not support the mailing of DDIF 
files to systems earlier than Version 5.1. As with non-VMS systems, the 
VMS Mail Utility returns the NOACCEPTMSG error message for systems 
earlier than Version 5.1, indicating that the remote node cannot accept the 
message format. 


DDIF File Access Within a Mixed Version Cluster 


In a cluster which contains both Version 5.1 or earlier systems, operations 
on DDIF files from systems earlier than Version 5.1 will cause inconsistent 
behavior. Records read from DDIF files on systems earlier than 

Version 5.1 will be fixed length 512 byte records, which contain DDIF 
control information in addition to the text context. Thus, typing a DDIF 
file on a system earlier than Version 5.1 does not produce readable text. 


Copying a DDIF file using a system earlier than Version 5.1 will not 
preserve the DDIF tag on the output file, which will cause problems in 
later access to the new file from a Version 5.1 system. 


However, using the Backup Utility from systems earlier than Version 5.1 
will create a correct backup of DDIF files, and will properly restore DDIF 
files from BACKUP save-sets. 


VMS RMS Interface Changes 


This section provides details about the changes made to the VMS RMS 
interface that support access to text in VMS DECwindows DDIF files. It 
includes information related to tagging files and accessing tagged files 
through the VMS RMS interface. The section also describes how tags are 
preserved at the VMS RMS interface. 
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9.3.1. Programming Interface for File Tagging 
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This release note focuses on the use of the DDIF tag for supporting VMS 
DECwindows files, although VMS RMS also supports file tagging for other 
compound document data formats. 


You can tag a file from the VMS RMS interface by using the $CREATE 
service in conjunction with a new extended attribute block (XAB) called 
the item XAB ($XABITM). The $XABITM macro is a general-purpose 
macro that was added to the RMS interface to support several Version 5.0 
features. Tagged file support involves the use of the two item codes shown 
in Table 9-1. | 


Table 9-1 Tag Support item Codes 


Item Buffer Size Function 
XAB$_STORED_SEMANTICS _ 64 bytes Defines the file semantics 
maximum established when the file is 
created 
XAB$_ACCESS_ SEMANTICS _ 64 bytes Defines the file semantics 
maximum desired by the accessing 
program 


The entries XAB$_STORED_SEMANTICS and XAB$_ACCESS_ 
SEMANTICS in the item list can represent either a control (set) function 
or a monitor (sense) function that can be passed to VMS RMS from the 
application program by way of the RMS interface. 


The symbolic value XAB$K_SEMANTICS_MAX_LEN represents the tag 
length. This value may be used to allocate buffer space for sensing and 
setting stored semantics for the DDIF file. 


Within any one $XABITM, you can activate either the set function or 

the sense function for the XAB$ STORED_SEMANTICS and XAB$_ 
ACCESS_SEMANTICS items, because a common field (KAB$B_MODE) 
determines which function is active. If you want to activate both the set 
function and the sense function for either or both items, you must use two 
$XABITM control blocks, one for setting the functions and one for sensing 
the functions. 


Each entry in the item list addressed by the $XABITM is made up of three 
longwords and a longword 0 that terminates the list. You can locate the 
item list anywhere within the readable address space for a process, but 
any buffers required by the related function must be located in read/write 
memory. If the item list is invalid, RMS returns a status of RMS$_XAB in 
the RAB$L_STS field and the address of the XAB in RAB$L_STV. 


The format and arguments of the $XABITM macro are as follows. Note 
that the block length field and the type code field are statically initialized 
by the $XABITM macro, or may be explicitly initialized using a high-level 
language. 


Support for Compound Documents 
9.3 VMS RMS Interface Changes 


FORMAT $XABITM /TEMLIST=item-list-address, 


_ { sensemode 
iced setmode \, 


NX T=next-xab-address 


Arguments 


The ITEMLIST argument defaults to 0 but a valid pointer must be 
specified when you use a XABITM. MODE defaults to sensemode. The 
symbolic offset, size, and a brief description of each XABITM field are 
described in the following list: 


The block length field (XAB$B_BLN) is a 1-byte static field that 
defines the length of the XABITM, in bytes. This field is initialized to 
the value XAB$C_ITMLEN. 


The type code (XAB$B_COD) field is a 1-byte static field that identifies 
this control block as a XABITM. This field is initialized to the value 
XAB$C_ITM. 


The XAB$L_ITEMLIST field is a longword field that contains the 
symbolic address of the item list. 


The XAB$B_MODE field is a 1-byte field that specifies whether the 
items can be set by the program. It contains either the symbolic value 
XAB$K_SETMODE or the symbolic value XAB$K_SENSEMODE 
(default). 


The XAB$L_NXT field is a longword field that contains the symbolic 
address of the next XAB in the XAB chain. A value of 0 (the default) 
indicates that the current XAB is the last (or only) XAB in the chain. 
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Example 9—1 illustrates a BLISS—32 program that tags a file through 
the RMS interface. The tag value shown is a 6-byte hexadecimal number 
representing the code for the DDIF tag. The VMS RMS program interface 
accepts only hexadecimal tag values. 


- To write to a tagged file without using an RMS extension, the application 
program must specify access semantics that match the file’s stored 
semantics. As shown in the example, the $CREATE service tags the file 
and the $CONNECT service specifies the appropriate access semantics. 


Example 9-1 Tagging a File 


MODULE TYPESMAIN ( 
IDENT = 'X-1', 
MAIN = MAIN, 
ADDRESSING MODE (EXTERNAL=GENERAL) 
) = 
BEGIN 
| 
FORWARD ROUTINE 
MAIN : NOVALUE; ! Main routine 
! 
! INCLUDE FILES: 
| 


LIBRARY 'SYSSLIBRARY:LIB’; 


OWN . 
NAM : SNAM(), 
-RETLEN, 
DDIF TAG : BLOCK[ 7, BYTE] 
INITIAL ( BYTE (3X! 2B’, 3%" OC" ,- Sx" 87", SX! 13" > ek O01" ek! 05" + eX" OL? J) 
FAB XABITM 
Sxabitm 
( itemlist= 
SITMLST UPLIT 
( 
(ITMCOD=XABS_ STORED SEMANTICS, 
BUFADR=DDIF TAG, 
BUFSIZ=csALLOCATION (DDIF_ TAG) ) 
)y 
mode = SETMODE), 
RAB XABITM 
Sxabitm 
( i1temlist= 
SITMLST UPLIT 
( 
(ITMCOD=XABS ACCESS SEMANTICS, 
BUFADR=DDIF TAG, 
BUFSIZ=SALLOCATION (DDIF_TAG) ) 
Vy 
mode = SETMODE), 
FAB : SFAB( fnm = ’TAGGED-FILE.TEST’, 
nam = NAM, 
mrs = 512, 
rim = FIX, 
fac = <GET,PUT,UPD>, 
xab = FAB XABITM), 
REC : BLOCK[512,BYTE], 
STATUS, 
RAB : SRAB( xab = RAB XABITM, 


(continued on next page) 
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Example 9-1 (Cont.) Tagging a File 


fab = FAB, 
rsz = 512, 
rb£ = REC, 
usz = 512, 
ubf = REC), 
DESC : BLOCK[8, BYTE] 
ROUTINE MAIN : NOVALUE = 
BEGIN 


STATUS = SCREATE( FAB = FAB ); 
IF NOT .STATUS 
THEN 
SIGNAL (.STATUS) ; 
STATUS = SCONNECT( RAB = RAB ); 
IF NOT .STATUS 
THEN 
SIGNAL (.STATUS) ; 
STATUS = SCLOSE( FAB = FAB ); 
IF NOT .STATUS 
THEN 
SIGNAL (.STATUS); 
END; 
END 
ELUDOM 


Accessing a Tagged File 
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INITIAL (QO); 


This section provides details of how VMS RMS handles access to tagged 
files at the program level. When a program accesses a tagged file, VMS 
RMS must determine whether and when to associate an RMS extension 
with the access. This is important to the programmer because an RMS 
extension may change the attributes of the accessed file. 


For example, a DDIF file is stored as a sequentially organized file having 
512-byte, fixed-length records. If the DDIF-to-text RMS extension is used 
to extract text from a DDIF file, the accessed file appears as a sequentially 
organized file having variable-length records with a maximum record size 
of 2048 bytes and an implicit carriage return. 


One consideration in determining whether an access requires the RMS 
extension is the type of access (FAB$B_FAC). When an application 
program opens a file through the VMS RMS program interface, it must 
specify if it will be doing record I/O (default), block I/O (BIO), or mixed 
I/O (BRO), where the program has the option of using either block I/O 
or record I/O for each access. For example, if block I/O operations are 
specified, VMS RMS does not associate the RMS extension with the file 


access. 


Another consideration is whether the program senses the tag when it 
opens a file. If the program does not sense the tag when it opens a DDIF 
file for record access, VMS RMS associates the RMS extension during the 
$OPEN and returns the file attributes that have been modified by the 


extension. 
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9.3.2.1 


9.3.2.2 


The final consideration is the access semantics the program specifies 
and the file’s stored semantics (tag). If the program specifies block I/O 
(FAB$V_BIO) operations, RMS does not associate the RMS extension and 
the $OPEN service returns the file’s stored attributes to the accessing 
program regardless of whether the program senses tags. 


File Accesses That Do Not Sense Tags 
This section describes what happens when a program does not use the 
XABITM to sense a tag when it opens a file. 


When a program opens a DDIF file for record operations and does not 
sense the tag, VMS RMS assumes that the program wants to access text 
in the file. In this case, VMS RMS associates the RMS extension, which 
provides file attributes that correspond to record-mode access. 


When a program opens a DDIF file with the FAB$V_BRO option and does 
not sense the tag, any subsequent attempt to use block I/O fails. If the 
program specifies block I/O (FAB$V_BIO) when it invokes the $CONNECT 
service, the operation fails because the file attributes returned at $0PEN 
permit record access only. Similarly, if the program specifies the FAB$V_ 
BRO option when it opens the file, and then specifies mixed mode 


_ (block/record) operations by not specifying RAB$V_BIO at $CONNECT 


time, block operations such as READ and WRITE are disallowed. 


File Accesses That Sense Tags 

VMS RMS does not associate the RMS extension as part of the $OPEN 
service if a program opens a DDIF file and senses the stored semantics. 
This allows the program to specify access semantics with the $CONNECT 
service. VMS RMS returns the file attributes, including the stored 
semantics attribute (tag value), to the program as part of the $OPEN 
service. 


When the program subsequently invokes the $CONNECT service, VMS 
RMS uses the specified operations mode to determine its response. If the 
program specified FAB$V_BRO with the $OPEN service and then specifies 
block I/O (RAB$V_BIO) when it invokes the $CONNECT service, VMS 
RMS does not associate the RMS extension. 


But if the program specifies record access or FAB$V_BRO when it opens 
the file and then decides to use record I/O when it invokes the $CONNECT 
service, VMS RMS compares the access semantics with the file’s stored 
semantics to determine whether to associate the RMS extension. If the 
access semantics match the stored semantics, VMS RMS does not associate 
the RMS extension. If the access semantics do not match the stored 
semantics, VMS RMS associates the access with the RMS extension. In 
this case, the program must use the $DISPLAY service to obtain the 
modified file attributes. If VMS RMS cannot find the appropriate RMS 
extension, the operation fails and the $CONNECT service returns the 
EXTNOTFOU error message. 


If the application program senses the file’s stored semantics, VMS RMS 
allows mixed-mode operations. In this case, mixed block and record 
operations are permitted because the application gets record mode file 
attributes and data from the RMS extension and block mode file attributes 
and data from the file. 
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Example 9-2 illustrates a BLISS—32 program that accesses a tagged file 
from an application program that does not use an RMS extension. 


Example 9-2 Accessing a Tagged File 


MODULE TYPESMAIN ( 
IDENT = 'X-1’, 
MAIN = MAIN, 
ADDRESSING MODE (EXTERNAL=GENERAL) 
—— 
BEGIN 
! 
FORWARD ROUTINE 
MAIN : NOVALUE; ' Main routine 
! INCLUDE FILES: 
| 


LIBRARY ’SYSSLIBRARY:STARLET’ ; 


OWN 
NAM : SNAM(), 
ITEM BUFF : BLOCK [ XABSK_ SEMANTICS MAX LEN, BYTE 1 
RETLEN, 
FAB XABITM 
Sxabitm 
( itemlist= 


SITMLST UPLIT 
( (ITMCOD=XABS STORED SEMANTICS, 
BUFADR=ITEM BUFF, 
BUFSIZ=XABSK_SEMANTICS MAX LEN, 
RETLEN=RETLEN) ), 
mode = SENSEMODE), 
RAB ITEMLIST : BLOCK[ ITMSS ITEM + 4, BYTE ], 
RAB XABITM : SXABITM 
( itemlist=RAB ITEMLIST, 
mode=SETMODE ), 
FAB : SFAB( fnm = 'TAGGED-FILE.TEST’, 
nam = NAM, 
fac = <GET,PUT,UPD>, 
xab = FAB XABITM), 


REC : BLOCK (512, BYTE]; 
STATUS, 
RAB : SRAB( xab = RAB XABITM, 
fab = FAB, 
rsz = 512, 
rbf = REC, 
usz = 512, 
ubf = REC), 
DESC : BLOCK[8,BYTE] INITIAL(0); 
ROUTINE MAIN : NOVALUE = 
BEGIN 


STATUS = SOPEN( FAB = FAB ); 
IF NOT .STATUS 
THEN 
SIGNAL (.STATUS) ; 
RAB_ITEMLIST[ ITMSW_BUFSIZ ] = .RETLEN; 
RAB ITEMLIST[ ITM$L BUFADR ] = ITEM BUFF; 
RAB _ITEMLIST[ ITM$W ITMCOD ] = XABS$ ACCESS SEMANTICS; 
STATUS = SCONNECT( RAB = RAB ); 
IF NOT .STATUS 
THEN 


ll 


(continued on next page) 
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Example 9-2 (Cont.) Accessing a Tagged File 


SIGNAL (.STATUS) ; 
STATUS = SCLOSE( FAB = FAB ); 
IF NOT .STATUS 
THEN 
SIGNAL (.STATUS) ; 
END; 
END 
ELUDOM 


9.3.3. Preserving Tags 


In order to preserve the integrity of a tagged file that is being copied or 
transmitted, the tag must be preserved in the destination (output) file. 
The most efficient way to use the RMS interface for propagating tags is to 
open the source file (input) and sense the tag using a $XABITM with the 
item code XAB$_ STORED _ SEMANTICS: 


ITEMLIST[ ITMSW_BUFSIZ ] 
ITEMLIST[ ITM$L_BUFADR ] 
ITEMLIST[ ITMSL RETLEN ] 
ITEMLIST[ ITMSW_ITMCOD ] 


XABSK_ SEMANTICS MAX LEN; 
ITEM BUFF; 

RETLEN; 

XABS STORED SEMANTICS; 


XABITM[ XABSB MODE ] = XABSK_SENSEMODE; 
STATUS = SOPEN( FAB = FAB ); 


Then create the destination (output) file and set the tag using a $XABITM 
with the item code XAB$ STORED_SEMANTICS: 


IF .RETLEN GTR 0 


THEN 
BEGIN 
ITEMLIST[ ITMSW_ITMCOD ] = XABS$_ STORED SEMANTICS; 
ITEMLIST[ ITMSL_ SIZE ] = .RETLEN; 
XABITM[ XABSB MODE ] = XABSK_SETMODE; 
END; 


STATUS = SCREATE( FAB = FAB ); 


END; 
END 
ELUDOM 
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9.4 Distributed File System Support for DDIF Tagged Files 


Version 1.1 of the Distributed File System (DFS) includes limited support 
for DDIF tagged files. You can create and read DDIF files on a DFS device 
when the DFS client node is running VMS Version 5.1. You can also use 
the DIRECTORY/FULL command to determine whether a DDIF file on a 
DFS device is tagged. 


You cannot use the SET FILE/[LNOJSEMANTICS command either to 
tag DDIF files or to remove the tags from DDIF files on a DFS device. 
Furthermore, the Backup Utility does not preserve the DDIF tag or the 
DDIF stored semantics for data files on a DFS device. 


9.5 VMS RMS Errors 


Four VMS RMS error messages signal the user when the appropriate error 
condition exists: 


e RMS$_EXTNOTFOU 
e RMS$_ SEMANTICS 
e RMS$_EXT_ERR 

e RMS$ OPNOTSUP 


The RMS$_EXTNOTFOU error message indicates that VMS RMS has not 
found the specified RMS extension. Verify that the file is correctly tagged, 
using the DIRECTORY/FULL command, and that the application program 
is specifying the appropriate access semantics. 


VMS RMS returns the RMS$_SEMANTICS error message when you try to 
create a tagged file on a remote system earlier than VMS Version 5.1 from 
a Version 5.1 system. 


VMS RMS returns the RMS$_EXT_ERR error when the DDIF RMS 
extension detects an inconsistency. 


VMS RMS returns the RMS$ OPNOTSUP error when the RMS DDIF 
extension is invoked by an RMS operation. For example, if the extension 
does not support write access to a DDIF file, verify that the application 
program is not performing record operations that modify the file. 
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This chapter describes the DCL command EXCHANGE/NETWORK and 
its error messages. 


EXCHANGE/NETWORK 


The EXCHANGE/NETWORK command allows the VMS operating system 
to transfer files to or from operating systems that do not support VMS file 
organizations. The transfer occurs over a DECnet network communications 
link that connects VMS and non-VMS operating system nodes. 


Using DECnet services, the EXCHANGE/NETWORK command can: 
¢ Transfer files between a VMS node and a non-VMS system node 
¢ Transfer a group of input files to a group of output files 


¢ Transfer files between two non-VMS nodes, provided those nodes 
share DECnet connections with the VMS node that issues the 
EXCHANGE/NETWORK command 


The EXCHANGE/NETWORK command imposes the following restrictions: 


¢ Transfers of files can occur only between disk devices. (If a disk device is 
not the desired permanent residence for the file, you must either move the 
file to a disk before issuing the command or retrieve the file from a disk 
after the command completes.) 


¢ The remote system must have a block size of 512 bytes, where a byte is 
8 bits long. 


¢ The nodes transferring files must support the DECnet Data Access 
Protocol (DAP). 


The VMS Record Management Services (RMS) facility provides VMS access 
to records in VMS RMS files. To transfer VMS RMS files between two nodes 
where both nodes are VMS nodes, use one of the other DCL commands 
(such as COPY, APPEND, or CONVERT), as appropriate. These commands 
recognize RMS file organizations and are designed to ensure that RMS record 
structures are preserved as your files are moved. 


Use the EXCHANGE/NETWORK command to transfer files between VMS 
nodes and non-VMS nodes when the differences in the file organizations 
would otherwise prevent the transfer or could lead to undesirable results. 
While COPY ensures that both the contents and the attributes of a 
replicated file are preserved, EXCHANGE/NETWORK is more flexible. 
EXCHANGE/NETWORK offers you explicit control of your record attributes 
during file transfers, with the opportunity to make a file usable on several 
different operating systems. 
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FORMAT 


EXCHANGE/NETWORK _input-file-specf, ... ] 
| output-file-spec 


PARAMETERS 


input-file-spec[, ... ] 

Specifies the name of an existing file to be transferred. Wildcard 
characters are allowed. Use a comma (,) to indicate multiple file 
specifications. 


output-file-spec 


Specifies the name of the output file into which the input is transferred. 


You must specify at least one field in the output file specification. If you 
omit the device or directory, your current default device and directory are 
used. The EXCHANGE/NETWORK command replaces any other missing 
fields (file name, file type, version number) with the corresponding field of 
the input file specification. 


EXCHANGE/NETWORK creates a new output file for every input file that 
you specify. 


You can use the asterisk wildcard character in place of the following: 
file name, file type, or version number. The EXCHANGE/NETWORK 
command uses the corresponding field in the related input file to name 
the output file. You can also use the wildcard character in the output file 
specification to direct EXCHANGE/NETWORK to create more than one 
output file. For example: 


S EXCHANGE/NETWORK A.A,B.B MYPC::%*.C 


This EXCHANGE/NETWORK command creates the files A.C and B.C at 
the non-VMS target node MYPC. 


A more complete explanation of wildcard characters and version numbers 
follows in the Description section. 


DESCRIPTION 
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The EXCHANGE/NETWORK command transfers files between VMS 
nodes and non-VMS nodes connected to the same DECnet network. 

If the non-VMS system does not support VMS file organizations, 
EXCHANGE/NETWORK can modify or discard file and record attributes 
during the transfer. However, if the target system is a VMS node, you 
have the option of applying new file and record attributes to the output 
file by supplying a File Definition Language (FDL) file, as described later 
in this section. EXCHANGE/NETWORK provides a number of defaults 
to handle the majority of transfers properly. However, in some situations, 
you need to know your file or record format requirements at both nodes. 


VMS File and Record Attributes 


All RMS files in the VMS environment include stored information, 
known as the file and record attributes, to describe the file and record 
characteristics. File attributes consist of items such as file organization, 
file protection, and file allocation information. Record attributes consist 
of items such as the record format, record size, key definitions for indexed 
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files, and carriage control information. These attributes define the data 
format and access methods for the VMS RMS facility. 


Non-VMS operating systems that do not support VMS file organizations 
have no means of storing file and record attributes with their files. 
Transferring a VMS file to a non-VMS system that is unable to store 

and handle file and record attributes can result in most of this information 
being discarded. Removing these attributes from a file can render it 
useless if it must be returned to the VMS system. 


Transferring Files to VMS Nodes 


When you transfer files to a VMS system from a non-VMS system, the 
files typically assume default file and record attributes. However, you can 
specify the attributes that you want the file to acquire in a File Definition 
Language (FDL) file. If you specify an FDL file with the /FDL qualifier, 
the FDL file determines the characteristics of the output file. This feature 
is useful in establishing compatible file and record attributes when you 
transfer a file from a non-VMS system to a VMS system. However, when 
you use an FDL file, you also assume responsibility for determining the 
required characteristics. 


See the VMS File Definition Language Facility Manual for more 
information on FDL files. 


Transferring Files to Non-VMS Nodes 


EXCHANGE/NETWORK discards file and record attributes associated 
with a VMS file during a transfer to a non-VMS system that does not 
support VMS file organizations. Be aware that the loss of file and record 
attributes in the transfer can render the output file useless for many 
applications. 


Selecting Transfer Modes 


The EXCHANGE/NETWORK command has four transfer mode options: 
AUTOMATIC, BLOCK, RECORD, and CONVERT. For most file transfers, 
AUTOMATIC is sufficient. The AUTOMATIC transfer mode option allows 
EXCHANGE/NETWORK to transfer files using either block or record I/O. 
The selection is based on the input file organization and the operating 
systems involved. 


Selecting the BLOCK transfer mode option forces EXCHANGE/NETWORK 
to open both the input and output files for block I/O access. The input file 
is then transferred to the output file block by block. Use this transfer 
mode when you transfer executable images. It is also useful when you 
must preserve a file’s content exactly, which is a common requirement 
when you store files temporarily on another system or when cooperating 
applications exist on the systems. 


Selecting the RECORD transfer mode option forces 
EXCHANGE/NETWORK to open both the input file and output file for 
record I/O access. The input file is then transferred to the output file 
record by record. This transfer mode is primarily used for transferring 
text files. 
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Selecting the CONVERT transfer mode option forces 
EXCHANGE/NETWORK to open the input file for RECORD access and 
the output file for BLOCK access. Records are then read in from the input 
file, packed into blocks, and written to the output file. This transfer mode 
is primarily used for transferring files with no implied carriage control. 
For example, to transfer a file created with DIGITAL Standard Runoff 
(DSR) to a DECNET-DOS system, you must use the CONVERT transfer 
mode option. To transfer the resultant output file back to a VMS node, use 
the AUTOMATIC transfer mode option. 


Wildcard Characters 


Wildcard characters are permitted in the file specifications and follow the 
behavior typical of other VMS commands with respect to the VMS node. 


When more than one input file is specified, but wildcards are not specified 
in the output file specification, the first input file is copied to the output 
file, and each subsequent input file is transferred and given a higher 
version number of the same output file name. Note that the files are not 
concatenated into a single output file. Also note that when you transfer 
files to foreign systems that do not support version numbers, only one 
output file results, and it is the last input file. 


To create multiple output files, specify multiple input files and use at least 
one of the following: 


e An asterisk wildcard character in the output file name, file type, or 
version number field 


¢ Only a node name, a device name, or a directory specification as the 
output file specification 


When you create multiple output files, EXCHANGE/NETWORK uses the 
corresponding field from each input file in the output file name. 


Use the /LOG qualifier when you specify multiple input and output files to 
verify that the files were copied as you intended. 


Version Numbers 


The following guidelines apply when the target node file formats accept 
version numbers. 


If no version numbers are specified for input and output files, the 
EXCHANGE/NETWORK command (by default) assigns a version number 
to the output files that is either of the following: 


e The version number of the input file 


e Aversion number one greater than the highest version number of an 
existing file with the same file name and file type 


When the output file version number is specified by an asterisk wildcard 
character, the EXCHANGE/NETWORK command uses the version 

numbers of the associated input files as the version numbers of the output / 
files. \ 
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If the output file specification has an explicit version number, the 
EXCHANGE/NETWORK command normally uses that number for the 
output file specification. However, if an equal or higher version of the 
output file already exists, no warning message is issued, the file is copied, 
and the version number is set to a value one greater than the highest 
version number already existing. 


File Protection and Creation/Revision Dates 


The EXCHANGE/NETWORK command treats an output file as a new file 
when any portion of the output file name is explicitly specified. When the 
output node is a VMS system, the creation date for a new file is set to the 
current time and date. However, if the output file specification consists 
only of wildcard characters, the output file no longer qualifies as a new file, 
and, therefore, the creation date of the input file is used. That is, if the 
output file specification is one of the following, the creation date becomes 
that of the input file: *, *.*, or *.*;*. 


The revision date of the output file is always set to the current time and 
date; the backup date is set to zero. The output file is assigned a new 
expiration date. (Expiration dates are set by the file system if retention is 
enabled; otherwise, they are set to zero.) 


When the target node is a VMS node, the protection and access control list 
(ACL) of the output file is determined by the following parameters, in the 
following order: 


1 Protection of previously existing versions of the output file 
2 Default protection and ACL of the output directory 


3 Process default file protection 


For an introduction to access control lists, see the VMS DCL Concepts 
Manual. 


On VMS systems, the owner of the output file usually is the same as the 
creator of the output file. However, if a user with extended privileges 
creates the output file, the owner is either the owner of the parent 
directory or the owner of a previous version of the output file, if one 
exists. 


Extended privileges include any of the following: 
e SYSPRV or BYPASS 
e System UIC 


¢ GRPPRV if the owner of the parent directory (or previous version of 
the output file) is in the same group as the creator of the new output 
file 


e An identifier (with the resource attribute) representing the owner of 
the parent directory (or previous version of the output file) 
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QUALIFIERS /BACKUP 
Modifies the time value specified with the /BEFORE or /SINCE qualifier. 
/BACKUP selects files according to the dates of their most recent backup. 
This time qualifier is incompatible with the other time qualifiers that 
also allow you to select files according to time attributes: /CREATED, 
/EXPIRED, and /MODIFIED. If you do not specify any of these four time 
qualifiers, the default is (CREATED. 


/BEFORE[=time] 


Selects only those files dated prior to the specified time. You can specify 
time as an absolute time, as a combination of absolute and delta times, 

or as one of the following keywords: TODAY (default), TOMORROW, or 
YESTERDAY. Specify one of the following time qualifiers with /BEFORE to 
indicate the time attribute to be used as the basis for selection: /BACKUP, 
/CREATED (default), /EXPIRED, or /MODIFIED. 


See the VMS DCL Concepts Manual for complete information about 
specifying time values. 


/BY OWNER|=uic] 
Selects only those files whose owner user identification code (UIC) matches 
the specified owner UIC. The default UIC is that of the current process. 


Specify the UIC using standard UIC format as described in the VMS DCL 
Concepts Manual. 


/CONFIRM 
/NOCONFIRM (default) 


Controls whether a request is issued before each file transfer operation to 
confirm that the operation should be performed on that file. The following 
responses are valid: 


YES NO QUIT 
TRUE FALSE CTRUZ 
1 0 ALL 


You can use any combination of uppercase and lowercase letters for word 
responses. Word responses can be abbreviated to one or more letters 

(for example, T, TR, or TRU for TRUE), but these abbreviations must be 
unique. Affirmative answers are YES, TRUE, and 1. Negative answers 
are NO, FALSE, 0, and the RETURN key. QUIT or CTRL/Z indicates that 
you want to stop processing the command at that point. When you respond 
with ALL, the command continues to process, but no further prompts are 
given. If you type a response other than one of those in the list, DCL 
issues an error message and redisplays the prompt. 


/CREATED (default) 

Modifies the time value specified with the /BEFORE or /SINCE qualifier. 
The /CREATED qualifier selects files based on their date of creation. This 
time qualifier is incompatible with the other time qualifiers that also allow 
you to select files according to time attributes: /BACKUP, /EXPIRED, and , 
/MODIFIED. If you do not specify any of these four time qualifiers, the | 
default is /CREATED. 
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/EXCLUDE=(file-spec[, ... ]) 


Excludes the specified files from the file transfer operation. You can 
include a directory but not a device in the file specification. Wildcard 
characters are allowed in the file specification. However, you cannot use 
relative version numbers to exclude a specific version. If you provide only 
one file specification, you can omit the parentheses. 


/EXPIRED 

Modifies the time value specified with the /BEFORE or /SINCE qualifiers. 
/EXPIRED selects files according to their expiration date. (The expiration 
date is set with the SET FILE/EXPIRATION DATE command.) This time 
qualifier is incompatible with the other time qualifiers that also allow you 
to select files according to time attributes: /BACKUP, /CREATED, and 
/MODIFIED. If you do not specify any of these four time qualifiers, the 
default is /CREATED. 


/FDL=fadl-file-spec 

Specifies that the output file characteristics are described in the File 
Definition Language (FDL) file. Use this qualifier when you require 
special output file characteristics. See the VMS File Definition Language 
Facility Manual for more information about FDL files. 


Use of the /FDL qualifier implies that the transfer mode is block by block. 
However, the transfer mode you specify with the /TRANSFER_MODE 
qualifier prevails. 


/LOG 


/NOLOG (default) 
Controls whether the EXCHANGE/NETWORK command displays the file 
specifications of each file copied. 


When you use the /LOG qualifier, the EXCHANGE/NETWORK command 
displays the following for each copy operation: (1) the file specifications of 
the input and output files, and (2) the number of blocks or the number of 
records copied (depending on whether the file is copied on a block-by-block 
or record-by-record basis). 


/MODIFIED 

Modifies the time value specified with the /BEFORE or /SINCE qualifier. 
The /MODIFIED qualifier selects files according to the date on which they 
were last modified. This time qualifier is incompatible with the other time 
qualifiers that also allow you to select files according to time attributes: 
/BACKUP, /CREATED, and /EXPIRED. If you do not specify any of these 
four time qualifiers, the default is (CREATED. 


/SINCE[=time] 


Selects only those files dated after the specified time. You can specify time 
as an absolute time, a combination of absolute and delta times, or as one of 
the following keywords: TODAY (default), TOMORROW, or YESTERDAY. 
Specify one of the following time qualifiers with /SINCE to indicate the 
time attribute to be used as the basis for selection: /BACKUP, /CREATED 
(default), /EXPIRED, or /MODIFIED. 


See the VMS DCL Concepts Manual for complete information about 
specifying time values. 
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/TRANSFER_MODE=option 
Specifies the I/O method to be used in the transfer. This qualifier is useful 
for all file formats. You can specify any one of the following options: 


Option Function 

AUTOMATIC Allows EXCHANGE/NETWORK to determine the 
appropriate transfer mode. 

BLOCK Transfers block by block. 

CONVERT{[=optionf, .. . J] Reads records from the input file, packs them 


into blocks, and writes to the output file in block 
mode. The options determine what additional 
information is inserted during the transfer. 


RECORD Transfers record by record. 


The AUTOMATIC transfer mode option allows EXCHANGE/NETWORK to 
determine the appropriate transfer mode. The default is the AUTOMATIC 
transfer mode. 


If you explicitly select the BLOCK transfer mode option, 
EXCHANGE/NETWORK opens both the input and output files for block 
VO. EXCHANGE/NETWORK then transfers the files block by block. 


If you explicitly select the RECORD transfer mode option, 
EXCHANGE/NETWORK opens both the input and output files for record 
I/O. The target system must support record operations, and the input file 
must be record oriented. 


If you select the CONVERT transfer mode option, 
EXCHANGE/NETWORK reads records in from the input file, packs 

them into blocks, and writes them to the output file in block mode. There 
are four options available with the CONVERT transfer mode to control the 
insertion of special characters in the records, as explained in the following 
paragraphs: 


e¢ CARRIAGE_CONTROL 

e COUNTED 

e FIXED CONTROL 

e RECORD_SEPARATOR=separator 


If you specify CARRIAGE_CONTROL, any carriage control information in 
the input file is interpreted, expanded into actual characters, and included 
with each record. 


If you specify COUNTED, the length of each record in bytes is included at 
the beginning of each record. The length includes all FIXED_CONTROL, 

CARRIAGE_CONTROL, and RECORD_SEPARATOR information in each 

record. 


If you specify FIXED CONTROL, all variable length with fixed control 
record (VFC) information is written to the output file as part of the data. 
This information follows the record length information if the COUNTED 
option was specified. 


f 
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If you specify RECORD_SEPARATOR, a 1- or 2-byte record separator is 
inserted between each record. Record separator characters are the last 

characters in the record. The three choices for separator characters are 
CR for carriage return only, LF for line feed only, or CRLF for carriage 

return and line feed. 


S PYCHANGE /NETWORK VMS EYLE.DAT FPoO::FORMIGN SYS. CAN 


In this example, the EXCHANGE/NETWORK command transfers 

the file VMS_FILE.DAT located in the current default device and 
directory to the file FOREIGN_SYS.DAT on the non-VMS node FOO. 
Because the /TRANSFER_MODE qualifier was not explicitly specified, 
EXCHANGE/NETWORK automatically determines whether the transfer 
method should be block or record I/O. 


mem ROA NOs / cia ah eee 7 te Soa ups tr ENT gal eee LE VT” 
2| $ PYCHANGR/NETWORK/TRANSFER MODS=BLOCK — 
$ “OC: : FOREIGN SYS.DAT VMS FLLE.DAT 


In this example, the EXCHANGE/NETWORK command transfers the file 
FOREIGN_SYS.DAT from the non-VMS node FOO to the file VMS_ 
FILE.DAT in the current default device and directory. Block I/O is 
specified for the transfer mode. 


S$ BXCKRANGE /NisTWORK/EDL=VMS FILE DEFINITION.FDL - 


a ra cil re eS) dat WAL YTELT wy a eee a) PEN BY PNT CN SORT iar wee Salas CE 9 TN te ETS 
S$ FOO; :+ REMOVE FILE. TXT VMo FiLE, DAT 


In this example, the EXCHANGE/NETWORK command transfers the file 
REMOTE_FILE.TXT on node FOO to the file VMS_FILE.DAT. The file 
attributes for the output file VMS_FILE.DAT are obtained from the File 
Definition Language (FDL) source file VMS_FILE_DEFINITION.FDL. For 
more information about creating FDL files, see the VMS File Definition 
Language Facility Manual. Because the qualifier /FDL is specified and the 
/TRANSFER_MODE qualifier is omitted, the transfer mode uses block I/O, 
by default. 


$ EXCHANGE/NETWORK - 
_$ /TRANSFER_MODE=CONVERT= (CARRIAGE CONTROL, COUNTED, ~ 
_$ RECORD SEPARATOR=CRLF, FIXED CONTROL) - 
_$ PRINT Wine. TXi FOO: :* - 


In this example, the EXCHANGE/NETWORK command transfers the file 
PRINT_FILE.TXT from the current default device and directory to the file 
PRINT_FILE.TXT on the non-VMS node FOO. The use of the CONVERT 
option with the /TRANSFER_MODE qualifier forces the input file to be 
read in record by record, modified as specified by the convert options 
described below, and written to the output file block by block. As many 
records as will fit are packed into the output blocks. 


The CONVERT option CARRIAGE_CONTROL specifies that carriage 
control information is converted to ASCII characters and inserted before 
the data or appended to the record, depending on whether prefix control 
or postfix control, or both, are used. The CONVERT option FIXED_ 
CONTROL specifies that any fixed control information be translated 

to ASCII characters and inserted at the beginning of the record. The 
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CONVERT option RECORD_SEPARATOR=CRLF appends the two 
specified characters, carriage return and line feed, to the end of the 
record. The CONVERT option COUNTED specifies that the total length 
of the record must be counted (once the impact of all the previous convert 
options have been added), and the result is to be inserted at the beginning 
of the record, in the first two bytes. 


EXCHANGE/NETWORK Command 
10.1 EXCHANGE/NETWORK Error Messages 


10.1 EXCHANGE/NETWORK Error Messages 


This section provides an alphabetical summary of the messages that can 
be generated by the DCL command EXCHANGE/NETWORK. A number 
of the messages are common to other utilities and DCL commands such as 
the Exchange Utility and the DCL command COPY. 


For information about the VMS style of presenting error messages, see the 
VMS System Messages and Recovery Procedures Reference Manual: Part I. 


It may be helpful to remove this section and file it as a temporary 
addendum to the VMS System Messages and Recovery Procedures 
Reference Volume until the next manual update becomes available. As an 
alternative, you might want to manually add just the following messages, 
which are the ones unique to the EXCHANGE/NETWORK command: 
BADDEV, CLOSEIN, CLOSEOUT, FDLPARSE, and RECPRN. 


10.1.1 Messages 
ATPC, at PC = 'xxxxxxxx’ 
Facility: Shared by several facilities 


Explanation: This message generally accompanies a message indicating 
a software failure. 


User Action: Take corrective action based on the accompanying 
messages. 

BADDEV, device is unsupported for transfer 
Facility: Exchange/Network Command 


Explanation: You attempted to transfer the file either to or from a device 
that the command does not support, such as magnetic tape. 


User Action: Correct an error in the device specification, if that is causing 
the problem, or try to use a different device. 

BADLOGIC, internal logic error detected, please report error ’ errorcode’ 
Facility: Shared by several facilities 


Explanation: The Exchange Utility or EXCHANGE/NETWORK 
command encountered an unexpected condition and terminated. 


User Action: Please submit a Software Performance Report (SPR), 
describing the error number and the commands that resulted in 
the message. If the error is only reproducible using a particular 
piece of media, send a copy of the media with the SPR. (Use the 
BACKUP/PHYSICAL command to make the copy.) 
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CLOSEIN, error closing ’filespec’ as input 
Facility: Exchange/Network Command 


Explanation: The EXCHANGE/NETWORK command encountered an 
error while closing an input file. This message is usually accompanied by 
a VMS RMS message indicating the reason for the failure. 


User Action: Take corrective action based on the associated message. 


CLOSEOUT, error closing ’filespec’ as output 
Facility: Exchange/Network Command 


Explanation: The EXCHANGE/NETWORK command encountered an 
error while closing the output file. This message is usually accompanied 
by a VMS RMS message indicating the reason for the failure. 


User Action: Take corrective action based on the accompanying message. 


COPIEDB, ‘input-filespec’ copied to ‘output-filespec’ (’nnn’ blocks) 
Facility: Shared by several facilities 


Explanation: The message displays the number of blocks copied, based 
on the size of the input files. This message is informational. 


User Action: None. 
COPIEDC, ‘input-filespec’ copied to ’output-filespec’ (’nnn’ records packed 
into ‘mmm’ blocks) 
Facility: Shared by several facilities 


Explanation: The message displays the number of records read in from 
the input file and the number of blocks written to the output file. This 
message is informational. 


User Action: None. 


COPIEDR, ‘input-filespec’ copied to ’‘ output-filespec’ (‘nnn’ records) 
Facility: Shared by several facilities 


Explanation: The message displays the number of records copied, based 
on the size of the.input files. This message is informational. 


User Action: None. 


FDLPARSH, fatal error encountered parsing FDL file 
Facility: Exchange/Network Command 


Explanation: An error occurred during the parsing of the FDL file 
supplied by the user. This message is issued with an accompanying 
message. 


User Action: Take corrective action based on the accompanying message 
and reenter the command. 
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HIGHVER, higher version of ‘ output-filespec’ already exists 
Facility: Shared by several facilities 


Explanation: An explicit version number is requested for an output file; 
the directory already contains an entry for the same file name and file type 
with a higher version number. This message is informational. Note that if 
the file is subsequently specified in a command, the system will locate the 
previously existing version if no version number is specified. The newly 
created output file will not be used. 


User Action: None. 


OPENIN, error opening ‘input-filespec’ as input 
Facility: Shared by several facilities 


Explanation: An input file cannot be opened. This message is usually 
accompanied by a VMS RMS message indicating the reason for the failure. 


User Action: Take corrective action based on the associated message. 


OPENOUT, error opening ’ output-filespec’ as output 
Facility: Shared by several facilities 


Explanation: An output file cannot be opened. This message is usually 
accompanied by a VMS RMS message indicating the reason for the failure. 


User Action: Take corrective action based on the associated message. 


READERR, error reading ' filespec’ 
Facility: Shared by several facilities 


Explanation: An input file specified cannot be read. This message is 
usually accompanied by a VMS RMS message indicating the reason for the 
failure. 


User Action: Take corrective action based on the associated message. 


RECPRN, ‘filespec’ contained ‘nnn’ records with invalid PRN fields (‘ mmm’ 
prefix ‘ppp’ postfix) 


Facility: Exchange/Network Command 


Explanation: The specified file contained one or more records with 
invalid printing control fields in the print file control area (PRN). The first 
byte of the control area constitutes a prefix area while the second byte 
constitutes a postfix area. These areas specify the carriage control to be 
performed before and after printing, respectively. A carriage return and a 
line-feed character were substituted for each invalid byte, and the file was 
copied. 


User Action: If the substitution is not acceptable, determine the cause of 
the PRN field error, fix it, and reenter the command. 
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SYNTAX, error parsing ‘string’ 
Facility: Shared by several facilities 


Explanation: The command syntax is invalid. The message displays the 
rejected portion of the command. 


User Action: Use the DCL command HELP or refer to the VMS DCL 
Dictionary for the correct syntax and reenter the command. 


WRITEERR, error writing ' filespec’ 
Facility: Shared by several facilities 


Explanation: The output file cannot be written. This message should be 
accompanied by a VMS RMS message indicating the reason for the error. 


User Action: Follow the recovery procedure for the specified VMS RMS 
message. 
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SET/SHOW DISPLAY Commands 


This chapter describes the DCL commands SET DISPLAY and SHOW 


DISPLAY. Please note that these commands can only be used if you have 
DECwindows installed. 


SET DISPLAY 


Allows the creation and modification of workstation display devices. The 
workstation display device is used as a mechanism to store the necessary 
information about how to access the workstation. 


FORMAT 


SET DISPLAY [display device] 


PARAMETERS 


display device 

If you specify the /CREATE qualifier, the parameter display device is 
defined as a logical name to point to this new device. If no device string is 
specified, DECW$DISPLAY is used. When a DECwindows program is run, 
it uses the logical name DECW$DISPLAY to find the workstation. 


If the /CREATE qualifier is not specified, then the device is modified based 
on the values of the other qualifiers specified. 


QUALIFIERS 


/CREATE 
Creates the display device by cloning the WSAO device. 


/[NOJPERMANENT 

Defaults to /PERMANENT if /CREATE is also used, which makes a device 
permanent even if the reference count of assigned channels goes to zero. 
Specifying a SET DISPLAY WSAn/NOPERMANENT causes the device to 
be deleted when the last channel is deassigned. 


/NODE=workstation 

Defines the node to be associated with this display device. When /CREATE 
is specified, NODE defaults to SYS$REM_NODE if defined, otherwise to 
SYS$NODE. This behavior allows the SET DISPLAY/CREATE command 
to be used whether you are logged in to the workstation locally, or are 
logged into a remote system after having entered the SET HOST command 
from the workstation. 


/TRANSPORT=transport-name 

Defines the transport to be used. Defaults to DECnet if /CREATE is also 
specified. Local is another acceptable value, provided the server and client 
are on the same node. 
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/SERVER:=server-number 


Defines the server to be associated with this display device. Defaults to 0 
if /CREATE is also specified. 


/SCREEN=screen-number 


Defines the screen to be associated with this display device. Defaults to 0 
if /CREATE is also specified. 


> A 


SHOW DISPLAY 


SHOW DISPLAY 


Displays the characteristics of a display device. 


FORMAT SHOW DISPLAY [display device] 


display device 
The parameter display device is used as the device name to list. If no 
device is specified, the logical name DECW$DISPLAY is used. 


PARAMETERS © 
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"key_modifiers" « 5—20 
"left" 4-23 
"length" * 4—25, 5-30 
"line" * 4-7, 4-8 
"line_editing"* 4-17 
"mouse_button"* 4-12 
"name" 4-9, 5-47 
"new_length"* 5-31 
“new_width" + 5-32 
"old_length"* 5-33 
"old_width" » 5-34 
"original_length"» 4-18 
"read_routine" * 5—19, 5-35 
"record_number"* 4—11 
"resize_action" * 5—40 
"right" * 4-27 
"screen_limits"* 5-36 
"scroll_bar"* 5-51 
"scroll_bar_auto_thumb" + 5-52 
"text" « 5-50 
"time" « 5-37 
"timer" * 4-19 
"top" * 4-29 
"ungrab_routine"* 5-38 
"widget_id"* 5—44 
"widget_info"* 5—48 
"width" * 4-31 
"window" « 4—14 

SYSTEM keyword parameter 
"enable_resize"* 5—39 
"resize_action"* 5—40 
"timer" « 4-19 

WIDGET keyword parameter , 
"callback_parameters"* 5—41, 7-6 
"widget_id"* 5—44 

widget variable parameter 
"name" + 5—47 
"text" 5-50 
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GET_INFO built-in procedure 
widget variable parameter (cont’d.) 
"widget_info"» 5-48 
widget_variable parameter 
"callback_routine"» 5—46 
window variable parameter 
"left" * 4-23 
"length" » 4—25 
"right" * 4-27 
"scroll_bar"« 5-51 
"scroll_bar_auto_thumb"* 5-52 
"top" « 4—29 
"width" » 4-31 
window_variable parameter 
"bottom" * 4—20 
example of use* 7-23 to 7-26, 7-26 to 
7-29 
"key_map_list"* 4-22 
Global selection 
determining ownership of * 5—26 
fetching grab routine for» 5—27 
fetching information about» 5—16 
fetching read request for» 5-24 
fetching read routine fore 5-19, 5-35 
fetching ungrab routine for* 5-38 
fetching wait time for * 5-37 
obtaining data from + 5-60 
reading information about* 5-59 
requesting ownership of * 5-66 
sending information about to an application 
5-104 
specifying expiration period for» 5-73 
specifying grab routine for» 5-68 
specifying read routine for* 5—71 
specifying ungrab routine fore 5-75 
support for* 7-2 to 7-4 
Grab routine 
fetching event in» 5-24 
global selection 
fetching * 5-27 
specifying * 5-68 
input focus * 5-78 
fetching * 5-27 
specifying » 5-80 


Icon 
fetching text of > 5-28 
specifying text for 5—77 
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Input focus 
determining ownership of * 5-29 
fetching grab routine fore 5-27 
fetching ungrab routine for 5-38 
requesting « 5—78 
specifying grab routine for* 5-80 
specifying ungrab routine for» 5—82 
support for* 7—4 7 

INT built-in procedure * 4-33 


J 


Journal file» 2-1 


K 


Key 

creating a name for* 5-53 
Key map list» 4—44 

example of fetching* 7-26 to. 7-29 
Key name 

fetching string equivalent of > 4—9 
Keyword 

fetching string equivalent of > 4—9 
KEY_NAME built-in procedure « 5-53 


L 


Line break 

in data from global selection * 5—60 
Line editing terminal attribute 

determining status of * 4—17 
List 

specifying as a resource values 7-8 
LOCATE_MOUSE built-in procedure» 4—34 
/LOG qualifier» 10-7 


Main window widget« 6-3 
MANAGE CHILDREN routine 

see MANAGE_WIDGET built-in procedure 
MANAGE CHILD routine 

See MANAGE_WIDGET built-in procedure 


MANAGE_WIDGET built-in procedure » 5—56 
example of use* 7-12 to 7-18 
Measurement 
converting units of* 4—2 
Menu bar widget * 6—3 
Message window 
in EVE* 6-3 
Modes 
of transferring files * 10-3 
/MODIFIED qualifier» 10-7 
MODIFY_RANGE built-in procedure « 4—36 
Mouse 
determining position of * 4-34 
determining support fore 4—47 
determining where drag operation originated « 
4-14 
positioning editing point to location of > 4—43 
Mouse button 
fetching information about» 4—12 
key map list fore 4—44 
Mouse pad 
implementing » 7-12 
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Name 
widget 
case sensitivity of > 5-4 
/NOCONFIRM qualifiers 10-6 
/NODE qualifiers 11-1 
/NOLOG qualifier * 10-7 


O 


Ownership 

global selection 
determining * 5—26 
losing * 5-38 
requesting» 5—66 

input focus 
determining « 5-29 
losing * 5—38 
requesting» 5-78 
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/PERMANENT qualifier» 11-1 
Pointer cursor * 4-34 
POSITION (MOUSE) built-in procedure * 4—43 
POSITION built-in procedure» 4—41 
example of use* 7-32 to 7-35 
PostScript back end* 8-8 to 8—11 
data loss in» 8-8 
data mapping ins 8-8 
processing options in» 8—9 
Procedures 
samples using EVE* 7-9 to 7-40 
Processing options 
in PostScript back end» 8—9 
in text back ends 8-8 


R 


Range 
moving delimiters of» 4—36 
video attributes of» 4—5 
Read request 
fetching » 5-24 
Read routine 
fetching» 5-19, 5-35 
specifying * 5—71 
READ_CLIPBOARD built-in procedure *» 5-57 
READ _GLOBAL_SELECT built-in procedure « 5—59 
example of use* 7-35 to 7-37, 7-37 to /-38 
Record numbers 4—41 
Resource 
supported data types for» 7—7 


S 


Sample procedures using VAXTPU built-in 
procedures* 7-9 to 7-40 
Screen 
enabling resizing of * 5—65 
specifying size of» 5-86 
updating 
controlling support for* 4—48 
SCREEN keyword 
using with widget-related built-in procedures « 6-3 
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Screen object 
in VAXTPU « 6-1 
/SCREEN qualifiere 11-2 
Scroll bar 
disabling» 5-88 
enabling « 5-88 
Scroll bar slider 
adjusting automatically « 5-52 
Scroll bar widget 
example of fetchinge 7-26 to 7-29 
Selection» 6-3 
dynamics 6-4 
found ranges 6-5 
statics 6-4 
using MODIFY_RANGE built-in to alter» 4-36 
Select range 
in EVE* 6-3 
/SERVER qualifiere 11-2 
SET (ACTIVE_AREA) built-in procedure » 5-61 
SET (DRM_HIERARCHY) built-in procedure » 5-64 
SET (ENABLE_RESIZE) built-in procedure » 5-65 
SET (GLOBAL_SELECT) built-in procedure » 5-66 
SET (GLOBAL_SELECT_GRAB) built-in procedure « 
5-68 
SET (GLOBAL_SELECT_READ) built-in procedure « 
5-71 
SET (GLOBAL_SELECT_TIME) built-in procedure « 
5-73 
SET (GLOBAL_SELECT_UNGRAB) built-in 
procedure * 5—75 
SET (ICON_NAME) built-in procedure * 5-77 
SET (INPUT_FOCUS) built-in procedure * 5—78 
SET (INPUT_FOCUS_GRAB) built-in procedure « 
_ 5-80 
SET (INPUT_FOCUS_UNGRAB) built-in procedure « 
5-82 
SET (KEY_MAP_LIST) built-in procedure *» 4—44 
SET (MODIFIED) built-in procedure » 4-46 
SET (MOUSE) built-in procedure * 4-47 
SET (RESIZE_ACTION) built-in procedure > 5-84 
SET (SCREEN_LIMITS) built-in procedure * 5—86 
SET (SCREEN_UPDATE) built-in procedure * 4—48 
SET (SCROLL_BAR) built-in procedure « 5-88 
example of use* 7-29 to 7-32 
SET (SCROLL_BAR_AUTO_THUMB) built-in 
procedure * 5-91 
example of use* 7-29 to 7-32 
SET (TEXT) built-in procedure *« 5-93 
SET (WIDGET) built-in procedure » 5-95 
example of use» 7-29 to 7-32, 7-32 to 7-35 
using to specify resource values * 7—7 
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SET (WIDGET_CALLBACK) built-in procedure « 
5-97 | 
example of use* 7-29 to 7-32 
using to specify callback routine» 7-5 
SET built-in procedure 
WIDGET « 7-5 
SET DISPLAY commands 11-1 
SHOW DISPLAY command: 11-3 
/SINCE qualifier» 10-7 
Slider * 5-52 
example of fetching» 7—-26 to 7-29 
Static selection » 6-4 
Stored semantics file attribute» 9-1 
See file tag 
STR built-in procedure » 4—49 
String data type * 3-2 


+ 


Text back end» 8-8 
data loss ins 8-8 
data mapping ins 8-8 
processing options in» 8-8 
Text front end* 8—7 
data loss in» 8-7 
data mapping in» 8-7 
document syntax errors in* 8-7 
external file references in» 8—7 
Title bar widget» 6-3 
TPUSWIDGET_INTEGER_CALLBACK callback 
routine» 7-5 
TPU$SWIDGET_STRING_CALLBACK callback routine 
° 7-5 
Transfer modes 
EXCHANGE/NETWORK command: 10-3 
/TRANSFER_MODE qualifier» 10-8 
/TRANSPORT qualifier» 11-1 


Ungrab routine 
global selection 
fetching s 5-38 
specifying * 5—75 
input focus 
fetching > 5-38 
specifying * 5-82 
UNMANAGE_WIDGET built-in procedure » 5—99 


User window 
in EVE* 6-3 


Value(s) 
assigning to widget resources * 5-95, 7-5 
VAXTPU 
built-in procedures * 1—1 
DECwindows« 1-1 
invoking» 2—1 
overviews 1-2 
relationship with DECwindows features * 1-2 
used with UlL* 1-4 
Version 2.2 defined* 1—1 
VMS « 1-1 
VAXTPU built-in procedures 
common to DECwindows and non-DECwindows « 
4-1 to 4-50 
related to DECwindows« 5—1 to 5-106 
Version number 
of VAXTPUe 1-1 
Version numbers 
assigning * 10-4 
VIEW commands 8-4 


Widget 
callback_parameters * 5—41 
case sensitivity of name* 5—4 
creating 5-2 
data type* 3-2 
defining a class of* 5-8 
deleting » 5-10 
fetching callback routine for» 5-46 
fetching name of* 5—47 
getting information abouts 5-48 
listing of * 7—1 
main window * 6-3 
managing 5—56 
menu bar 
in VAXTPU « 6-3 
scroll bare 5-51, 5-88 
scroll bar slider» 5-52 
setting resource values of* 5—95 
setting text of > 5—93 
title bars 6-3 
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Widget (cont’d.) 
unmanaging « 5-99 
widget_id* 5—44 
Widget children 
managing « 5-56 
unmanaging * 5—99 
Widget resources 
data types of» 7-7 to 7-8 
specifying * 7-7 
Wildcards 
EXCHANGE/NETWORK commands 10-4 
Window 
bottom 
example of fetching» 7-23 to 7-26 
command 
in EVE* 6-3 
determining bottom of» 4—20 
determining boundaries and size of» 4—20 to 
4—32 
determining last column of * 4-27 
determining leftmost column of* 4-23 
determining length of * 4—25 
determining top of > 4—29 
determining width of» 4-31 
function of 
in VAXTPU compared with DECwindows » 
6-3 
key map list 
example of fetching» 7-26 to 7-29 
length 
example of fetching» 7-23 to 7-26 
message 
in EVE* 6-3 
scroll bar ine 5-51, 5-88 
scroll bar slider in» 5-52 
setting mouse key map list fors 4—44 
top 
example of fetching» 7-23 to 7-26 
user 
in EVE* 6-3 
width 
example of fetching» 7-26 to 7-29 
Workstation» 11—1 
WRITE_CLIPBOARD built-in procedure « 5-101 
example of use* 7-18 to 7-20 
WRITE_GLOBAL_SELECT built-in procedure « 
5-104 
example of use* 7-38 to 7-40 
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X resource 
fetching value of * 5-14 
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How to Order Additional Documentation 


Technical Support 


If you need help deciding which documentation best meets your needs, call 800-343-4040 before placing 
your electronic, telephone, or direct mail order. 


Electronic Orders 


To place an order at the Electronic Store, dial 800-DEC-DEMO (800-332-3366) using a 1200- or 2400-baud 


modem. If you need assistance using the Electronic Store, call 800-DIGITAL (800-344-4825). 


Telephone and Direct Mail Orders 


Your Location Call 


Continental USA, 800-DIGITAL 
Alaska, or Hawaii 


Puerto Rico 809-754-7575 
Canada 800-267-6215 
International 

Internal! 


Contact 


Digital Equipment Corporation 
P.O. Box CS2008 
Nashua, New Hampshire 03061 


Local DIGITAL subsidiary 


Digital Equipment of Canada 

Attn: DECdirect Operations KAO2/2 
P.O. Box 13000 

100 Herzberg Road 

Kanata, Ontario, Canada K2K 2A6 


Local DIGITAL subsidiary or 
approved distributor 


SDC Order Processing - WMO/E15 
or 

Software Distribution Center 
Digital Equipment Corporation 
Westminster, Massachusetts 01473 


1For internal orders, you must submit an Internal Software Order Form (EN-01740-07). 


Reader’s Comments VMS Version 5.1 
New Features Manual 
AA—-MG29A-TE 


Please use this postage-paid form to comment on this manual. If you require a written reply to a software 
problem and are eligible to receive one under Software Performance Report (SPR) service, submit your 
comments on an SPR form. 


Thank you for your assistance. 


I rate this manual’s: Excellent Good Fair Poor 


Accuracy (software works as manual says) 
Completeness (enough information) 
Clarity (easy to understand) 

Organization (structure of subject matter) 
Figures (useful) 

Examples (useful) 

Index (ability to find topic) 

Page layout (easy to find information) 
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OOOOO0O000 
OOOOOOO00 
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I would like to see more/less 


What I like best about this manual is 


What I like least about this manual is 


I found the following errors in this manual: 


Page Description 


Additional comments or suggestions to improve this manual: 


I am using Version of the software this manual describes. 
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